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IMTRODUCTTON 



nitS provides a variety of commands for file inanipuiation and 
viewing. Editing commands allow the user to insert and change the 
text in a file, Viewing coffireands (viewsi^jecs) allow the yser to 
control how the system prints or displays the file. Line 
truncation and control of statement numbers are examples of these 
viewing facilities. 

Occasionally one may need more sophisticated view controls than 
those available with the viewing features of MLS, 

For example! one may want to see only those statements that 
contain a particular word or phrase. 

Or one wilght want to see one line of text that compacts the 
information found jn several longer statements, 

one might also wish to perform a series of routine editing 
Operations without specifying each of the MLS commands over and 
over again, or build commands for specific applications, 

User^written progratt^s roay tailor the presentation of the 
information in a file to particular needs, EXp^tienced users may 
write programs that edit files automatically. 






2b 



2b I 



2b2 



2c 



2d 




This document describes three general types of programs? 

--simple filters that control what is portrayed on the user's 
teletype or d|spiay (Parts One and Two), 

•-programs that may modify the statements as they decide 
whether to print them (Parts Two and Three), 

--those that, liKe commands, are explicitly given control of 
the 30b and interact with the user (Part Four), 

user programs that control what material is portrayed take 
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effect when HhS presents a sequence ot statements In response 

to a command like Print (or Jump in DNliS), 2f4 

m processing such a commands nhS looRs at a sequence of 
statements f examining each statement to see if It satisfies 
the vieisspecs then in force. At this point NiaS may pass the 
statement to a user»written program to see if it satisfies 
the requirements specified in that program, if the user 
program returns a value of TRUE> the (passed) statement is 
printed and the next statement in the sequence is tested? if 
FALSE, HIS 3ust goes on to the next statement, 2f4a 

While the program is examining the statement to decide whether 

or not to print lt# it may modify the contents of the 

statement t Such a program can do anything the user can do with 

UhS commands, 2f5 

For more complex tasKSf a user program function as a 
speciai-purpose sutosystem having (in addition to tne may 
supervisor commands) one or more commands, Once such a program 
is loaded, it can be used 3ust like any of the standard 
subsystems, (The MESSAGE program is an example,) 2f6 

This document Is divided into five part$! 2g 

Part One is Intended for the general usert 2gi 

It is a primer on content Analyzer Patterns^ allowing the 

niS User to set up simple yet powerful filters whrough which 

he may view and edit files. This does not involve learning 

the tlO language nor programming. This section can stand 

alone, and the general Clf somewhat experienced) MS user 

should find it very useful, 2gla 

Part Two is intended for the tieginning programmer, 2g2 

It presents a hasty overview of LIO programming, with enough 
tools to write simpie programs. This is intended as an 
introduction for the beginning user programmer, who we 
assume Is reasonably familiar with r^LS (its commands^ 
subsystems, and capabilities) and has some aptitude for 
programming, 2g2a 

Part Three is a more complete presentation of LtO, 2g3 

It is Intended to acquaint a potential 1^10 programmer with 
enough of the language and ^LS environment to satisfy most 
requirements for automated editing programs. Many of the 
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concepts in Part Two are repeated in Part Three so that it 
may stand alone as an Intermediate progra»ffler*s reference 
guide, This is the section in which to begin looking for 
answers to specific questions, 2g3a 

Part Four presents more advanced i<iO toois and an introduction 

to QUhr aliowing command syntax specification, 2g4 

This shouid give the programmer the ability to write 

programs wntch work across filesf wnich move through tiles 

in other than the standard sequential order # and which 

interact with the user. It allows the programmer to build 

user*attachable subsystems with cofufiiands looking very !«uch 

like standard NLS facilities, 2g4a 

Part Five presents a nurober of subjects of interest to the 

advanced LIO progarower, 2g5 

if^e suggest that those who are new to Lio begin by acgulring a 
thorougb understanding ot part One, Then Part Two snouid be 
studied one section at a tii'^e, pausing between sections to try 
out the concepts presented by actually writing patterns or 
programs that put the new ideas to experimental use. Actual 
experience is of at least as much value as this tutorial, 
Tutorial guidance should be requested from apc through your 
architect. It you have prOPlems at any point i you should get 
help from ARC before proceeding to the next section, 2g6 

Note? Fbr syntactical correctness^ some examplfs Include 

constructs not yet defined in the text? they will be 

discussed soon thereafter, 2g6a 

For examples of user programs which serve a variety of nee<3inf 
examine the attachable subsystems in the <PRDGRAHS> directory and 
their descriptions in Help, for information about commands 
mentlonedr ask for the programming subsystem with the NtS Help 
command, 2h 
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PART ONE; Content Analyzer patterns 3 

Section 1 8 introdMction 3a 

Content analysis patterns cannot aftect the format in which a 
statement is printed, nor can they edit a file. They can only 
deterrpine whether a statement should be printed at all. They are, 
in a sense, a filter through which you may view the file. More 
complex tasks can be accomplished through programs, as described 
later in this document, 3al 

The Content Analyzer filter is created by typing in (or selecting 

from the text in a file) a string of a special form which 

describes those statements which will pass through the filter. 

This string is called the "Content Analyzer Pattern", Each 

statement is checked against the pattern before it is printed? 

only statements that are described by the pattern will be printed, 3a2 

Some quick; examples of Content Analyzer Patterns? 3a3 

'( $LD ') will Show all statements whose first character is an 

open parenthesis, then any number of letters or digits, then a 

close parenthesis, 3a3a 

["blap"3 will show all statements with the string "blap" 

somewhere in them, 3a3b 

SINCE O-JUN^TS OOjOO) will show all statements edited since 

June 3, 1975 3a3c 

The next part of this section will describe the elements which 
make up Content Analyzer Patterns, followed by some examples. The 
final subject of this section is how to put them to use, 3a4 
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Section 2j Patterns 3b 

Elements of Content Analyser Patterns 3bl 

content Analyzer patterns describe certain things the system 
ffiust checK before printing a statement. It may check one or a 
series Of things, isach test is called an eieffientj the inany 
possible eleii^ents will be described below, 3bla 

The Content Analyzer searches a statement from the 
beginning^ character by character^ for described elements • 
AS it encounters each elesnent of the pattern^ the content 
Analyzer checKs the statement for the occurrence of that 
element? if the test fails, the whole statement is failed 
(unless there was an "or" condition, as described later) and 
not printedi if the test is passed, an Imaginary marker 
moves on to the next character in the statement? and the 
next test in the pattern is considered. 

For example! if the next element in the Content Analyzer 
pattern IS "IjD", th© imaginary marker will move over th® 
next character and go on to test the next element of the 
pattern only if the next character is a letter or a digit? 
otherwise the whole statement fails to pass the filter. 

The pattern may include any seguence of the following elementsi 

the Content Analyzer moves the marker through the statement 

checking for each element of the Pattern in %\xtm 3folb 

Literal String elements 3blc 

*c »* the given character Ce,g, a lower case c) 

"string" ••the given string (may include non»printing 
. Charactersy sucn 'as ■■spaces! ' 

Character class elements 3bld 

CH — • any character 

L w- lowercase or uppercase letter 

D »- digit 

Uh •-uppercase letter 

LL •- lowercase letter 
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ULD •* uppercase letter# or diciit 

LLD •» lowercase letten or digit 

LD -- lowercase or uppercase letter, or digit 

nw *^ not a letter not digit 

PT "• any printing character (letters* digltSf punctuation) 

MP •• any non*prlnting character Ce,g, spaces, control 
characters) 

special nonwprintlng character elements 3ble 

SP *» a space 

TAB •• tab character 

CR •• a carriage return 

hW -*• line teed character 

EOlu •* TEMEX BOlt (end of line) character 

ALT •• altnjode character 
Special elements 3b if 

ENDCHR w^ beginning and end of every Uh& statement j can't 
scan past itj not considered a character 

TRUE ** is true without checking anything in statement (used 
with OR constructs, as described below) 

ID* Id •» statement created by user whose Ident Is given 

lD# Id •» statement not created by user whose Ident is given 

BEFORE (d»t) •* statement edited before given date and time 

SINCE (d"»t) -* statefnent edited since given date and time 

E,g, BEFORE (i OCT 1974 00:00) ; 

The date and time irtust both appear in the parentheses. 
It accepts alwost any reasonable date and time syntax. 



Page 7 



ARC 34044 Rev, 5 DEC 75 



&ARC-APP 4*PEC»75 20:25 34044 
Mhs Programmers' Guide 
Part One: patterns 



Exawpies of vaXld dates? 

17-APR-74 17 APRIlu 74 

APR*.17*74 17/5/1974 

APR n 74 5/17/74 

APRIL 17, 1974 

Examples of valid tiroesj 

U 12:13 1234:56 

1234 1S56AM 

U56.EST 1200MOOM 

16!30 (l.e, 4:30 PH) 
12:00:00AM Ci,e, Hdrilght) 
ll:59:59AM-»EST (i,e, late morning) 
12:00:01AM Cl.e, early morning) 

Scan direction 3b ig 

< •- set scan direction to tl^e left 

> •» set scan direction to the right 

The defawlt, re^initialized tor each new statementf is 
scan to the right from before the first character in the 
statement (beginning to end). 

Modifying Elements 3b2 

Several operators can modify any of the elements except the 

"special elements": 3b2a 

mUmBER •'? multiple occurrences 3b2b 

A number preceding any element other than one of the 
"Special elements" means that the test will succeed only if 
it finds exactly that many occurrences of the element, it 
there aren't that many, the statement will be rejected. 
Even though there may be more, it will stop after that many 
and go on to check the next element in the pattern, 

3lJli means three upper case letters 

$ '^ range of occurrences 3b2c 

A dollar sign (s) preceding any element other than the 
"Special elements" means "any number of occurrences of". 
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This may Include zero occ^J^rrences, It Is good practice to 
put the element itself in parentheses, 

$('*) means any number of dashes 

h numtoer in front of the dollar siqn sets a lower lirait, 

3$ CD) means three or more digits 

A number after the dollar sign sets an upper limit for the 

search. It will stop after that nuroher and then check for 

the next element in the patterni even if it could have found 

more, 

$3ClfD) means from zero to three letters or digits 

5$7(PT) means from 5 to 7 (inclusive) printing 
characters 

11 •• floating scan 3b2d 

To do other than a character by character checjc^ you may 
enclose an element or series of elements in square brackets 
C), The content Analyzer will scan a statement until the 
elementCs) is found, (If the element is not in square 
bracKetSf the whole statement falls if the very next 
character or string fails the test of the next element,) 
This test will reject the statement if it can't find the 
element anywhere in the statement, if it succeeds^ It will 
leave the marker for the next test just after the string 
satisfying the contents of the square brackets, 

"start" means check to see if the next five characters 
are;,! -s t .a r t* ; 

C'start") means scan until it finds the stringi star 

[301 means scan until it finds three digits, 

C 3D '?] means scan until it finds three digits followed 
by a colon 

* -^w negation 3b2e 

If an element is preceded by a minus sign ^t the statement 
Will pass that test if the element does not occur. 
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-LD weans anything other than a letter or digits such as 
punctuation, invisibies, etc, 

NOT -- negation 3b2£ 

NOT Will be TRUE if the element or group of elements 
enclosed in parentheses following the not is false, 

NOT LD win pass if the next Character is neither a 
letter nor a digit. 

Combining Elements 3b3 

You may put together any number of any of these elements to 

form a pattern. They may be combined in any order. Spaces 

within the pattern are ignored (except in literal strings) so 

they may be used to make reading easier for you, 3fo3a 

e,g, ISPT t%HLS?" J$D] ^$P 

l,e, one or more printing characters # then scan for ,l*ltSj 
followed by one or more digits, then check that the next 
character Is not a space 

More sophisticated patterns can by written by using tbe Boolean 
logical expression features of |40, combinations of elements 
may In turn be treated as single elements, to be modified or 
combined using logical operators, 3b3b 

Generally, an expression is executed left to right. The 
following operations are done in the given orders 

.( .)■ ' 
■ / 

NOT 

AND 

01? 3b3c 

( ) 3b3d 

Parentheses (and square brackets for floating scans) R»ay be 
used to group elements, it Is good practice to use 
parenthesis liberally. 



3b3e 



/ means "either or"j the bracketed element, consisting of 
two or more alternatives, will be true If either (any) 
element Is true. 
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(3D h / 4D) means either three digits and a letter or 
four digits. 

Since the siash is executed belore nOf, iOf D / 'h will be 
true if the next character is NEITHER a digit nor the letter 
«h". It is the same as NOT CD/*h) , 

Sometimes you may want want the scan to pass your marker 
over something if It happens to be there Can optional 
element ) » "TRUE" is true without testing the statement ♦ II 
the other tests fatlf the imaginary marker is not moved, 

(D / TRUE) looks for a digit and passes the imaginary 
marker over it, If the next character is not a digit, it 
will just go on to the next test element in the pattern 
without moving the marker and without failing the test, 
(This test always passes,) 

i,e. It is used to scan past somethingCs) which may or 
may not be there* 

Since expressions are executed from left to rights it does 
no good to nave TRUE as the first option, (if it is first, 
the test will immediately pass tithout trying to scan over 
any elements,) 



AND 



3b 3 f 



OR 



kun means both of the two separated groups of elements must 
be true for the statement to pass, 

Sli^CE (3/6/73 OOiOO) AMD IDINDM means Statements written 
since March 6f 1973 by someone other than mdh. 



OB means the test will oe true if either of the separated 
elements is true, it does the same thing as slash^ but 
after »AND" and »MOT" have been executed, allowing greater 
flexibility, 

D AND hW OH UL means the same as CD AND LLD) OR UL 
D AND LiD / UL means the same as D AND (llD / UL) 

While such patterns are correct and succlnctt parentheses 
make for much clearer patterns. Elements within 
parentheses are taken as a group; the group will be true 
only if the statement passes all the requirements of the 



3b3g 
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group. It is a good Idea to use parentheses whenever 
there might be any afflblguity. 
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Section 3: Examples of Content AnaXyzer Patterns 3c 

D 2$LD / ["CA"] / C'Content Analyzer") 3cl 

This pattern win match and pass any of three types of HhS 

statements; those beginning with a numerical digit foliowed by 

at least two characters which may be either letters or digits, 

or statements with either of the strings "CA" or "Content 

Analyzer" anywhere in the statement, 3cla 

Note the use of the square bracKets to permit a floating 
scan •'• a search for a pattern anywhere in the statement. 
Mote also the use of the slash for alternatives » 

BEFORE (25»JAN*72 12:00) 3c2 

This pattern win match those statements created or modified 

before noon on 25 ilanuary 1972, 3c2a 

(ID a HGL) OP CID s MDM) 3c3 

This Pattern will match all statements created or modified toy 

users with the identifiers «HGl«*' or "NDM", 3c3a 

C(2L (SP/THUE) / 2D) D % Wl 3c4 

This patt^srn will Katch characters in t^e ^orm of phone nunibers 
anywhere in a statement, Numbers matc^^ed wiay have an 
alphabetic exchange followed by an optional space (note the use 
of the TRUE construction to accomplish this) or a numerical 
exchange, 3c4a 

Examples include da 6«6200, DA6»6200f and 326'»6200, 

CENDGHR] < »cba« 3c5 

This will pass those statements ending with '♦abC, It will go 

to the end of the statementf change the scan direction to left# 

and checJc for the characters »cba'% f>iote that since you are 

scanning bacKwards# to find »abc*' you must look for '»cba'*. 

Since the "cba" is not enclosed in square brackets, it must be 

the very last characters in the statement, 3c5a 
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Section 4s Using the Content Analyzer 3d 

content An«»lyzer Patterns may be entered in two wayst 3dl 

1) from the BASE subsystem^ use the commands 3dla 
set Content (pattern) to pattERM OK 

2) From the PHOGRAHS subsysteiRf use the commands 3dlh 

Compile Content (Pattern) PATTEK?^ OK 

OK ffseans "Coroniand Accept" ^ a control«D or^ 
in TMLS (by default) a carriage return. 

In either cases 3d2 

1) Patterns may foe typed in from the keyboard, or 3d2a 

2) they may be text In a file, 3d2fo 

in this case, the pattern will be read frons the first 
character a<ldressec[ and continue until It finds a semicolon 
(S) so yog must put a semicolon at the end of the pattern 
(In the file), 

Vlewspec j n^u^t be on Cl»e, Content Analyzer off) when entering 

a pattern, 3d2c 

Entering a content Analyzer pattern does two thlngss 3d3 

i) compiles a small user program from the characters in the 

pat tern f and 3d3a 

2) takes that program and "institutes*' it as the current 

Content Analyzer filter program, deinstituting any previous 

patterng 3d3b 

"instituting" a program means selecting It as the one to 
take effect when the Content Analyzer is turned on. You may 
have more than one program compiled but only one instituted. 

When a pattern is deinstltuted, it still exists in your 
program buffer space and may be instituted again at any time 
with the command in the PROGRAMS subsystem! 

institute Program PPOGRam^mame (as) Content (analyzer) OK 
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Tile programs may be refered to by number instead of 
naie. They are numbered sequentially, the first 
entered being number I, 

All the programs you have compiled and the one you have 
instituted may be listed with the command in the PROGRAMS 
subsystem: 

Show Status (of programs buffer) OK 

Programs maY build up m your program buffer. To ciear the 
prograiT! buffer f use the programs subsystein command: 

Delete All (programs in buffer) OK 

We recommend tl^at you do tl^is before each new pattern, 
unless you specifically want to preserve previous 
patterns t 

To invoke the Content Analyzers 3d4 

When viewspec i is on, the instituted Content Analyzer program 
(if any) will checK every state^ient before it is printed (or 
displayed), 3d4a 

If a statement does not pass all of the regulrements of the 
content Analyzer program, it will not be printedf 

m DNl^Sf if no statements from the top of the screen 
onward through the file pass the content Analyzer filter^ 
the word "Empty" will be displayed, 

Notei you will not see the normal structure since one 
statement may pass the content Analyzer although its source 
does not, Viewspecm (statement numbers on) will help you 
determine the position of the statement in the file, 

if^hen vlewspec K is on, the instituted Content Analyzer filter 
will checK until it finds one statement that passes the 
requirements of the patterh. Then, the rest of the output 
(branch, plex, display screen, etc,) will be printed without 
checking the content Analyzer, 3d4b 

When viewspec j is on, no content Ahalyzer searching is done. 

This is the default state? every statement in the output 

(branch, plex, display screen, etc,) will be printed, i^ote 

that if j# and )c are mutually exclusive. 3d4c 
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fjotes on the use of content Analyzer filters: 3<I5 

Sonie NLS coiRiBands are always affected toy the current vlewspeCs 
(including i#j^ or k): 3d5a 

Output 

Jump (in DNLS) 

Print Cln TMlS) 

Host NLS coff-iPands ignore trie Content Analyzer in their editlnt , 

The following BASK) subsystem comjnands offer the option of 

specifying viewspecsf or «Filters'*, (which may turn on the 

Content Analyzer) which apply only for the purpose of that one 

command and affect what statements the command worKs on (only 

those staten^ents which pass the filter will be copied^ moved# 

etc,? structure will be adjusted): 3d5b 

Copy 

Delete 

Hove 

Substitute 

At this point, it would be wise to practice until you becowe 

proficient at Content Analyzer patterns, you might begin by 

trying to use some of the patterns given in the above examples^ 

and then try writing a few patterns of your own. These patterns 

are both a useful NLS tool and a basic component of many LIO 

programs, we further recommend that you contact ARC via your 

architect before you begin the next part, 3d6 
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PART Tmt Introduction to LIO Programiing 4 

section 15 Content Analyzer Programs 4a 

Introduction 4al 

When you specify a content Analyzer Pattern, the PROGRAMS 

subsystem constructs a profrai? wnicn ioo)cs for the pattern in 

each statement and only displays the statement if the pattern 

matching succeeds. You can gain wore control and do more 

things if you build the program yourself. The program will be 

used just like the simple pattern program and has many of the 

same limitations. Programs are written in nh$ just llKe any 

other text file. They tben can be converted to executable code 

by a compiler. This code resides (Or is loaded) in your 

programs buffer spacey it can be instituted as the current 

Content Analyzer filter program like a Content Analyzer 

Pattern, 4ala 

Program structure 4a2 

If you specify a Content Analyzer Pattern^ NLS compiles a small 

program that looks liice this (with the word "pattern'* stan<Slng 

for whatever you typed in) s 4a2a 

PROGRAM name 

(name) PROCEDURE; 

IF FIMD pattern THEN RETURN (TRUE) ELSE RBTtlRH(rAtSE) | 

END, 

rimsM 

LlO programs must begin with a header statement, the word 

PROGRAM (all caps) followed by the name of the first procedure 

to be executed (all lower-case). This name is also the name of 

the program. If the program is being compiled into a file (to 

be described at the end of this section), the word FILE should 

be substituted for the word PROGRAM, E,g, 4a2b 

PROGRAM first 

or 
FILE deldir 
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fl^otes the Cont#nt Analyzer compiler JiaKes up a program 
name consisting of UPt'xxxxx, where 

# is a seguential number i tne first pattern being number 
onet and 

xxxxx Is the first £ive characters of your pattern,) 

E,g« UPii$l.0CP 

The body of a program consists of a series of PECliARATlOW 

statements and PROCEDURES (in any order) which are blocks of 

instructions t In the above case* the program consisted of only 

one small procedure and no declarations, Hhen the program is 

loaded into your programs buffer space, the declarations 

reserve space in the system to store infor«ation (variables), 

When the program is used as a Content Analyzer filter program, 

the first procedure is called for each statement. It may in 

turn call other procedures and access variables in the program 

or in the HLS system, E,g, 4a2c 

DECLARE xr y# z f (aesGribed below) 
(first) PROCEDURE ? 

* 9 * 

The end of the program is delimited by the word "FINISH" (in 
ail upper case). The compiler stops at that point, so any text 
after that in the NLS source file win be ignored, 4a2d 

comments may be enclosed in percent signs (%) anywhere in the 

program* even in the middle olLlO statements. The Li 

compiler will ignore them, 4a2e 

Except Within literal strings, variable J^ames and special LIO 

words, spaces are ignored, it is good practict to use them 

liberaliy so that your program will be easy to react. Also, n^B 

file structure is ignoredy statements will be read 

seguentially, regardless of their level, structure is, 

however, very valuable in maKlng the program readable, and it 

is good practice to use it in close correiatlon to the 

program^s logical structure, for instance# the programmer 

usually malces each of the elements of a program (declarations, 

procedyres, and riNiSM) separate statements, below the header 

statement in file structure. This point will be discussed 

further later, 4a2f 

So far# we have file which looks something llKej 4a2g 
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PROGRAM naroel 

DECLARE f,» ? 

DECLARE ,,, r 

(naroel) PROCEDURE j 

(naffle2) procedure ? 

Procedure Structure 4a3 

Each proce<3ure must toegin with its header statement , This 

header stateient is a name enclosed in parentheses followed by 

the word PROCEDURE, and terminated by a semicolon, E.g, 4a3a 

(hanie) PROCEDURE j 

The body of the procedure may consist of Local declarations, 

then Lie statements. An LIO statement is any program 

instruction, terminated by a semicolon. The body roust at some 

point return control to the procedure that called it. All this 

will be further discussed later, 4a3b 

The procedure must end with the terminal statement: 4a3c 

END, 
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Example (tfie actyal 1,10 statements in this example will becone 

clear as you read on)! 4a4 

PPOGP^W compare % Content analyzer. Displays statement if 
first two visitoles are the same, % 4a4a 

treserve space for ("declare") four text pointers naiea 
"pti» through «pt4*'% 

DECLAPE TEXT POII^TER ptl, pt2, pt3, pt4? 
%reserve 100 characters of space tor each ot two string 
variables named "vlst" and "vis2"r% 

DECLARE STRING visltlOO|, Vis2ii003j 
(compare) PROCEDURE j 

%if find two vlsibleSf set pointers around first two 
visltoles (Strings Of printing Characters)! 

IF FIND $NP •ptl 1$PT *pt2 $NP *pt3 l$PT *pt4 THEN 
BEGIN 

%put visibles in strings% 
*visl* » Ptl pt2 t 
#vls2*^ Pt3 pt4 J 
%compare contents Of strings # return and display 
the stateif^ent if identtcal% 

IF #visl# ?5 #Vis2« THEW RETURN(TRUE)f 
ENDf 
%otherwise, return and don't display% 

returi^ (false) ? 
ewd. 

FINISH 

Declaration Statements 4a5 

AS you may have guessed lro» the above example^ content 

Analyzer programs can manipulate variables (liJce text pointers 

and strings)^ while patterns cannot, 4a5a 

Text Pointers 4a5b 

A text pointer points to a particular location within an ns 
statement (or into a string, as described later). 

The text pointer points between two characters in a 
statement. By putting the pointers between characterSf a 
single pointer can be us^d to roarl^ both the end of one 
string ^nd the beginning of the string starting with the 
next Character, 

Text pointers are declared with the following Declaration 
statements 
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DECLARE TEXT POINTER name ; 

Strings 4a5c 

String variables nold text, i^fhen they are aeciared^ the 
maxiraurn number of characters Is set. 

To declare a strlngj 

DECLARE STRING nafflernuni3 J 

num Is the maximum number of characters allowed for the 
string, 

»^ • g , 

DECLARE STRING istr Ing tlOOj j 

declares a string named "Istrlng" with a maximum length 
of 100 characters and a current length of characters 
(it's empty), 

you can refer to the contents of a string variable by 
surrounding the name with asterisks, E.g, 

#lstring# is the string stored in the variable named 
•♦Istrlng", 

(Refering tp istrlnq without the asterisKs represents 
only the first computer word of tne string. This is 
rarely needed, ) 

you can put the text between two text pointers in a string 
variable with the LlO statement! 

*lstring* •, ptrl ptr2 i 

where ptrl an<3 ptr2 are the names of previously declared 
and set text pointerst and Istring is a previously 
declared string variable. 

These variables will retain their value from one statement to 

the next. Other types of variables and their use will be 

discussed in detail in Part three^ Section 3, 4a5d 

Body of the Procedure 4a6 

RETURN statement 4a6a 



page 21 



ARC 34044 Rev, S DEC 75 



&ARC*API> 4*PEC»75 20825 34044 
Hhs Prografflffiers* Guide 
Part Two: Content Analyzer Programs 



Mo matter what it does, every procedure royst retarn control 
to the procedure that called it, The statement which does 
this Is the RETURN statement, E,g, 

RETURN y 

A RETURN Statement may Pass values to the procedure that 
called it» The values must be enclosed m parentheses after 
the word RETURN. E^g, 

RETURN (1,23,47) J 

A Content Analyzer program must return either a value of 
TRUE or of FALSE, If It returns the value true (i), the 
statement will be printed* if it returns FALSE (Q), the 
statement will not be printed, l,e, 

RETURN (TRUE)? will print the statement 
RETURN (FALSE) J will not print the statement 

The RETURl^ statement often is at the end of a procedure, but 

it need not be. For example, in the middle of the procedure 

you may want to either RETURN or go on depending on the 
result of a test. 

Other than the requirement of a ReTURIi statement! the body of 
the procedure is entirely a function of the purpose of the 
procedure, A few of the many possible statements will be 
described here? others will be introduced in part Three of this 
document, 4a6b 



FIND Statement 

One Of the most useful statements for Content Analyzer 
programs is the find statement. The FIND statement 
specifies a content Analyzer pattern to be tested against 
the statements and text pointers to be manipulated and set, 
starting from the current character position (that invisible 
marker refered to in Section 1), if the test succeeds, the 
character position is moved past the last character read, 
If at any point the test fails, the character position is 
left at the position prior to the fiMD statement. The 
values of text pointers set in the statement prior to the 
failing element will remain as set? others of course will 
not be changed, 

FIND pattern ; 



4a6c 
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The Current cr^aracter position Is initialized to BEFORE THE 
FIRST CHARACTER r and the scan direction is Initialized to 
left to RIGHT, FOR EACH MEW STATEMENT passed to the Content 
Analyzer prograii. 

Any simple Content Analyzer pattern Cas describe above) is 
valid In a Fim statement. 

In additlonf the following elements can be Incorporated in 
tne pattern? 

#stringnai!i€# 

the contents of the string variable 
"•ptr 

store current scan position into the text pointer 
specified by ptr, the name of a declared text pointer 

^nm ptr 

bac^ up the specified text pointer bV the specified 
nUfpber (MUM) of characters. If NUM is not specified, 
t will be assuRied, Backup is in the direction 
apposite to the current scan direction. 



Ptr 



set current character position to this position, ptr 
is the name of a previously set text pointer. 



srcptr) 



The current Character Position is set to the front of 
the statement In which the text pointer ptr is set and 
scan direction is set from left to right. 



SE(ptr) 



The Current Character Position is set to the end of 
the stateroent In which the text pointer ptr Is set and 
scan direction is set from right to left. 
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BETWEEM ptrl ptr2 (pattern) 

search liinlteia to between positions specified, ptr is 
a previously set text pointer i the two must be in the 
san?e statement or string. Current Character position 
is set to first position before the pattern is tested, 

BETWEEN ptl pt2 (2D (J $MP) 

FINDS may be used as expressions as well as free-standing 
statements. If used as an expressjoni for example m IF 
statements # it has the value TRUE If all pattern elements 
within it are troe and the value FALSE if any one of the 
elements is false, E,g, 

IF FIND pattern THEN ,,, ; 

Complicated example: 

IF FIMD '•Sf $NP '( $(LD/**) •) t», " #Str#3 SECSf) $NP 
% THEN RETURN (TRUE) ELSE RETURN (FALSE) J 

IF Statement 4a6d 

IF causes execution of a statement if a tested expression Is 
TRUE. If it is FALSE and the optional ELSE part is present, 
the statement following the ELSE is executed. Control then 
passes to the statement immediately following the IF 
statement, 

IF testexp THEN statement j 

IF testexp Tmn statementl else statement2 ; 

The statements within the IF statement can be any valid LlO 

statement* but are not followed by the usual semicolon j the 

whole IF statement is one LIO statement and is followed by a 
semicolon, 

K^ f g • ■ 

IF FIWD (SDl THEH RETUR^CFALSE) ELSE RETURN(TRUE) j 

Programming Style j File structure 4a7 

The compiler which converts your UhS text to code ignores UhS 
file structure. This allows you to use structure to maJce your 
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program text easier to read ana understand, Logical use of 

structure often facilitates ti^e actual programwing tasK as 

well. Some conventions have developed at ARC in this respect* 

although flexibility Is essential. These should seem obvious 

and logical to you, 4a7a 

All declarations and PROCEDURE statements should be one 
level below the PROGRAM statement. 

All local declarations (not yet descrihecj) and code should 
be one level below the PROCEDURE statement , 

It is good style# and makes for much easier programming, to 
list what you want to do as comment statements (in percent 
signs) at the level below the PROCEDURE statementt Then you 
can go bacJc and fill in the code that accomplishes the tasK 
described in each comment statement. The code should go one 
level below the comment* 

It is also worthwhile to put comments in individual 
statements Whose purpose is not obvious, 

We will later describe how to bloc»c a series of statements 
where one is requlredi These bloclcs should go a level below 
the statement of which they are a part. 

File structure should follow the logical structure of the 
program as Closely as possible, E,g, 

If FIND C5D1 

THEK RETURNCfHUE) 

EI^SB: RETURII(FALSE)| 

Using content Analyzer Programs 4a8 

Once the cohtent Analyzer program has been written (in an Nl^s 
file)f there are two stePs ih using It, Firsti the ptotram 
must be "compiled," i,e» transiated into machlhe-readable code? 
the compiled code is "loaded** into a space reserved for user 
prograitis (the user programs buffer), Secondly# the loaded 
program must be ^ihstituted*' as the current Content Analyzer 
program, 4a8a 

There are two ways to compile and load a programt 4a8b 

I) You may coRipile a program and load it into your programs 
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buffer alX In one operation, in this case, the program 
header statement must have the word paOGRAN in it, m&n the 
user resets his job or logs off, the compiled code will 

disappe,ar, , 

Firstf enter the Programs subsystem with the conjinand; 

Goto Programs OK 
Then you may compile the program with the commandi 

Compile LlO (user program at) SOURCE OK 

SOURCE is the nhs tile address o* the PROGRAH 
statement, 

2) you may compile a program into a TENEX code file and then 
load it into your buffer in a separate operation. The 
program can then be loaded from the file Into your user 
programs buffer at any time without recompiling. The header 
statement must use the word FILE instead of PROGRAM, Use 
the PROGRAMS subsystem command: 

Compile File (at) soURCg (using) LlO (to file) fII^E^AMe 

OK 

The FILENAME must be the same as the program's name. 

The code file is called a REL (RELocatable code) file, 
l/^henever you wish to load the program code into the user 
programs bufferr use the PROGRAMS subsystem command: 

Load Program (fiie) FILENAME OK 

once a compiled program has been loaded (by either route), it 
must be instituted. This Is done with the PROGRAMS subsystem 
command: 4a8c 

institute Program progRAM*NAMe (as) Content (analyzer 
program) OK 

The named program will be instituted as the current Content 
Analyzer filter, and any previously Instituted program will 
be deinstituted (but will remain in the buffer). 

Again, the programs in the buffer are numbered, the first in 
being number one. You may use the number instead of the 
program's name as a shorthand for PROGRAm-NAME, 
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To InvoKe the Content Analyzer using whatever program is 

currently instituted, use the viewspec if j, or Kf as described 

in part One, Section 4 C3d4), 4a8d 

Probleffls 4a9 

Given these few constructs, you should now be abie to write a 

number oi useful content Analyzer programs. Try programming 

the following? 4a9a 

1) Show those statements which have a number somewhere in 
the first 20 characterst 

2) Show those statements where the first visible in the 
statement is repeated somewhere in the statement. 
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Sairple soXutionsj 4a9b 

Proble!« 1 

PROGRAM numtoer 

DECLARE TEXT POINTER ptrl, ptr2 ? 
CnuiTtber) PROCEDURE j 

FIND •ptrl $20CH *ptr2 ? 
IF FIND BETWEES ptrl ptr2 ( Id} } 
THEH RETURN C TRUE) 
EhSt RETURN (FALSE) J 
END, 
FINISH 

Alternate solution to protoiero 1? content Analyzer Filter 

$20CH < CDj 

Problent 2 

PROGRAM vis 

DECIARE TEXT POINTER ptrl, ptr2 j 
DECLARE STRING StrfSOOl ; 
Cvis) PROCEDURE f 

FIND $NP *ptrl 1$PT -ptr2 I 

#str« ^ ptrl ptr2 j 

IF FIND ptr2 CNP *str* NP3 
THEN RETURN (TRUE) 
ELSE RETUBNCFAliSE) J 
END, 
FINISH 
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Section 2s Content Analyzer Programs i Modifying Statenents 4b 

Introauction 4bl 

content Analyzer programs may edit the. statements as well as 

decide whether or not they are printed. They are very useful 

where a series of editing operations has to foe done time and 

time again, This section will introduce yoy to these 

capabilities. All these constructs will be covered in detail 

in Part Three, 4bla 

A content Analyzer program hsi^ several limitationst it can 

manipulate only one file and it can loolc at statements only in 

sequential order Cias they appear in the file). It cannot back 

up and rewexamine previous statements, nor can it sKlp ahead to 

other parts of the file, it cannot interact with the user. 

Part Four provides the tools to overcome these limitations, 4blb 

String construction 4b2 

Statements an<3 the contents of string variables may be modified 

by either of the following two statements: 4b2a 

ST ptr ^ stringlist t 

The whole statement in which the text pointer named "ptr*' 
resides will be replaced by the string list (to be 
described in a minute) » 

ST ptr ptr « stringlist ; 

The part of the statement from the first ptr to the 
second ptr will be repi^ced by the string list, 

ptr may be a previously set text pointer or SFCptr) or 
SE(ptr). 

The content of string variables may be replaced with the string 
assignment statement? 4b2b 

#strlngname* ^ stringlist j 

The string list (stringlist) may be any series of string 
designators, separated by commas. The string designators may 
be any of the following (other possibilities to be described 
later): 4b2c 
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a string constants e.g. "ABC or 'w 

ptr ptr 

the text between two text pointers prevlouslF set in 
either a statement or a strina 

*stringnan5e# 

a strlnci name in asterisks* refer ing to the contents of 
the string 

E,g,s 4b2a 

ST pi p2 * ^string* j 

Or 
ST pi ^ srcpt) pif #string*f p2 SE(p2)? 

(Notes these have exactly the same meaningt) 

Exarople? 4b 3 

PROGRAM delsp % Content analyzer. Deletes all leading 
spaces froir statements, % 4b3a 

%reserve space for ("declare") a text pointer named "pt"! 

DECLARE TEXT POINTER ptj 
(delsp) PROCEDURE j 

%if any leading spaces* scan past them and set pointer% 

IF FIND l$SP *pt THEN 

%repiace statement with text from pointer to 
statement end% 

ST pt «. pt SE(pt); 
%returnf don't display anything% 

RETURW (FALSE) ; 
END, 
FINISH 

More Than One Change per statement 4b4 

Part ol a text pointer Is a character count. This count stays 
the same until the text pointer is again set (to some other 
position), even though the statement has been edited. If* for 
example f you have the statement 4b4a 

abode fg 

and if you have seta pointer between the "d" and the "e**, it 
will always point between the fourth and fifth characters in 
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the statement. It you then delete the character "a"! your 
pointer will be between the «e" and the "f"^ now the fourth and 
fifth characters, ror this reason, yoa should begin a series 
of edits with the last one In the statement and worJ^ baclcwards 
through the statement, 4b4b 

controlling Which Statements are Modified 4b5 

In TNLSr the Content Analyzer program will ^e called for 

commands which construct a printout of the file (print ana 

Output), The program will run on every statement for which It 

Is called (e,g, every statement In the branch during a Print 

Branch command) which pass all the other viewspecs. Once you 

have written, complied, and Instituted a program which does 

some editing operation, the Print command Is the easiest way to 

run the program on a statement, branch, plex, or group, 4b5a 

In DNl.5, the system will call the content Analyzer program 
whenever the display Is recreated (e,g, vlewspec f and the vlump 
commands), and also for the Output commands. If the program 
returns TRUE, It will only run on enough statements to fill the 
screen, it Is safer to have programs that edit the file return 
FALSE, Then when you set vlewspec I, It will run on all 
statements from the top of the display on, and when It Is done 
It will display the word "Empty", At that point, change to 
vlewspec 1 and recreate the display with vlewspec F, then all 
statements Including the changes will be displayed. You can 
control which statements are edited with level viewspecs and 
the branch only (g) Or plex only (1) viewspecs, and by 
positioning the top Of your window, 4bSb 

After having rwn your program on a file, you may wish to Update 

to permanently Incorporate the changes In the file, it Is wise 

to Update before you run the program so that# If the program 

does something unexpected, you can Delete Modifications and 

return to a good file, 4b5c 

Problems 4b6 

Try writing the following programsi 4b6a 

1) Remove any Invisibles from the end of each statement, 

2) Make the first word a statement name surrounded by 
parentheses. 
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Sainple solutions} 4b6b 

Problem l 

PROGRAM endinv 

DECLARE TEXT POINTER ptr j 
(endlnv) PROCEDURE j 

IF FIWD *ptr SE(ptr) i$NP *ptr 
THEN ST ptr • SF(ptr) ptr ; 
RETURN CFAI.SE) J 
ENP, 
FlIJISH 

Problem 2 

PROGRAM makenawe 

DECl*ARE TEXT POINTER ptr I, ptr2 ; 

(makename) PROCEDURE ; 

IF FiMD $NP *ptrl l$l.D •ptr? 

THEN ST ptrl ^ 't, ptri ptr2,^), ptr2 SECptr2)? 

RETURN (FALSE) 
EW)^ ■ ■■■■ 
FINISH 
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PART THREE: Basic LIO Programming 5 

Section Is The yser Program Environment 5a 

Introduction Sal 

User^wrltten content Analyzer programs are called in the 
process Of creating a viev ot an nls file e,g.> with a Print 
coRiffiand in TNLSi with any of the output commands r and with the 
aump command in DNLSi Said 

The sequence generator provides statements one at a time j 
the Content Analyzer may then check each one. Finally^ the 
formatter prints it or puts it on the screen. 

Thus if one had a user Content Analyzer program compiled and 
instituted, one could have a printout made containing only 
those statements in the file satisfying the pattern. 

Attachable subsystems are independent of this portrayal 

proCeSSf although they are welcome to malce use of it. They 

consist of commands, which may utilize all the powers of NLS, salb 

The Sequence Generator 5a2 

In the portrayal process, the seguence generator loojcs at 
statements one at a time, beginning at the pojnt specified by 
the user, It observes viewspecs lilce level truncation in 
determining which statements to pass on to the formatter. When 
the seguence generator finds a statement that passes all the 
viewspec requirements, it sends the statement to the formatter 
and waits to be called again for the next statement in the 
sequence, 5a2a 

For example, the viewspecs may indicate that only the first 
line of statements in the two highest levels are to be 
output. The default NLS seguence generator will produce 
pointers only to those statements passing the structural 
filters? the formatter will then truncate the text to only 
the first line before it displays or prints the statement. 

Content Analyzer Filters 5a3 

one of the viewspecs that the sequence generator pays attention 
to is "iM »• the viewspec that indicates whether a user Content 
Analyzer filter is to be applied to the statement, if this 
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vlewspec is on, the sequence generator passes control to a user 
Content Analyzer program, which looks at the statenent and 
decides whether it should be included in the sequence. If the 
statement passes the content Analyzer (i,e, the user program 
returns a value of TRUEDf the sequence generator sends the 
statement to the forn^atterj otherwise, it processes the next 
stateinent in the sequence and sends it to the user Content 
Analyzer program for verification, (The particular user 
program chosen as a filter is determined by what program is 
instituted as the current Content Analyzer prograirif as 
described below,) 5a3a 

m the process of examining a statement and deciding whether 
or not it should be printedt the Content Analyzer prograni 
may edit the text of the statement. These edits appear in 
the partial copy, just as if the user had made them himself. 
This provides a powerful mechanism for automatic editing, 

in DNLSf if you display any statementSf the program will 
stop after filling the screen. If you are not dlsplayihg 
any statements^ the program will run on either the whole 
file# a plex (viewspec l)r or a branch (viewspec g). These 
along with level clipping viewspecs give one precise control 
over what statements in the file will be passed to the 
program. 

The Portrayal Formatter 5a4 

The formatter ^rrahges text passed to it bY the sequence 
generator in the style specified by other viewspecs. The 
formatter observes viewspecs such as line truncation, length 
and indenting; it also formats the text In accord with the 
requirements of the output device, 5a4a 
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Section 2s Program Structure 5b 

An Hl»S yser prograifi consists of the following elementsi which must 

be arranged In a definite manner with strict adherence to 

syntactic punctuations 5bl 

The header • 5bla 

a statement consisting of the word PROGRAM, followed by the 
name of a procedure m the program, program execution wiH 
begin with a call to the procedure with this n^me^ 

PROGRAM name 

The PROGRAH statement may have a statement name in 
parentheses? it wiu be ignored. 

The word Flhf. should be substituted for the word PROGRAM if 
the code is to be compiled into a file to be saved^i 

The FILE statement may have a statement name? if so, that 
name will be used as the code^ftie symbol. You must not 
follow the word FlhE with a name if there is a statement 
name preceding FILE, 

The body « 5blb 

consists of declarations and procedures in any orders 

1) declaration statements which specify information 
about the data to be processed by the procedures in the 
program and enter the data identifiers in the program's 
symbol table^ terminated by a semicolon, E,g, 

DECLARE Xfyiz t 

DECLARE STRING testCSOOJ J 

REE 'X,' Zj 

Declaration statements will be covered in section 3 
(5c), 

2) procedures which specify certain execution tasK:s, 
Each procedure must consist of s 

the procedure name enclosed in parentheses followed by 
the word PROCEDURE and optionally an argument list 
containing names of variables that are passed by the 
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calling procedure lor referencing within the called 
procedure. This statement must be terminated by a 
senjicoioht Et g» 

(name) PROCEDURE f 

(name) procedure (paramlf parai!i2) } 

Yow should always include a comment in the 
procedure statement breif ly sumparlzing the 
function of the procedure. 

the body of the procedure which may consist of liOCAL* 
REFf and 1^10 statements t 

LOCAli and REF declarations within a procedure must 
precede executable code. They will be covered m 
Section 3 (5c), 

LtO statements will be covered in Sections 4 and 5 
C5d) CSe), 

A RETURB Statement must be Included at some 
point r to pass control back to the calling 
procedure, if it is missing, execution will run 
off the end of the procedure and an Il*liEGAL 
INSTRUCTIDM will ocCUr, 

the statement that teri^'inates the procedure (note the 
final period)! 

END» 

The program terminal statement • 5blc 

FINISH 

Mote; this is a signal to the compiler to stop 
compiiationj it aoe® '^ot mean stop e^e^w^lon. Any text 
after that in the WLS source file will be ignored, 

Notes on Program spiriting style 5b2 

Except for within literal strings ^ variable nameSi and special 

LjO reserve<3 wordSf spaces are ignored, it is good practice to 

use them liberally so that your program will be easy to read, 5b2a 

comments may be enclosed in percent signs (%) wherever spaces 
are allowed. They will be ignored by the compiler. It is good 
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practice to use the level below the procedure stsitement for 
con?roentSf filling in the code that executes the commented 
tunctloh at the level below the comment. It is also wise to 
add coRiroents to any Individual statements whose function is not 
obviousf particularly calls on other procedures, 5b2fo 

You tRay find it convenient to add a comment to the FILE 
statement including t^e information needed by tl^e Compile 
File command, E,g, 

FILE program % (LiO,) to (directoryiProgram.subsys# ) % 

Also# NLS file structure is ignored. Structure is# however? 

very valuable in making the program readable! and it is good 

practice to use it in close correlation to the program's 

logical structure, 5b2c 

An example of a simple LIO program 1$ provided here. The reader 
Should easily understand this program after having studied this 
document, 5b 3 

PROGRAM delsp % content analyzer. Deletes all leading 
spaces from statements. % 5b3a 

%reserve space for ("declare") a text pointer named "pt"% 

DECLARE TEXT POINTER ptj 
(delsp) PROCEDURE f 

%lf any leading spaces, scan past them and set pointer% 
IF FIND 1$SP *pt THEN 

%replace Statement holding pt with text from 
pointer to statement end% 
ST pt « Pt SE(pt)j 
%return, don't display% 

RETURN C FALSE) ? 
EWD, 
FINISH 
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Section 3: Declarations 5c 

Introduction 5cl 

LlO declarations provide Information to the compiler about the 
data that is to be accessed! they are not execwted, Every 
variable used in the progra'" roust be declared soraewhere in the 
systein (eltf^er in your program or in the MLS system), 5cla 

there are a number of types of variables available! each with 

its own declaration statement? the wost frequently used are 

discussed here, (Cowplete documentation Is available in the 

1.10 Reference Guide ** 7052^) 5clb 

Variables 5c2 

Six types of variables are described in this documents simple, 
constants, arrays, text pointers, strings, and referenced. 
Each is represented by an identifier^ some ynique lowercase 
name, Eacb can be declared on three levels: local, global, or 
external, 5c2a 

Local Variables 5c2b 

A locai Variable is Known ahd accessible only to the 
procedure in which ^t appears, Locai variables inust appear 
in a procedure argument list or be declared in a procedure's 
LOCAL declaration statements (to be explained below). Any 
LOCAL declarations must precede the executable statements in 
a procedyre. 

Local variahles in the different procedures may have the 
same name without conflict, A global variable may not be 
declared as a local variable and a procedure name may be 
used as neither, in such cas®s the name is considered to be 
multiply defined and a compilation error results. 

Global Variables 5c2c 

Glopai Variabies Qte defined in the program's DECLARE 
statements, variables specified m t^ese declarations are 
outside any procedure and may be used by all procedures In 
the program. 

External Variables 5c2d 
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External variables are defined in the program's DECIUARE 
statements or in the nls systerp program. 

Variables specified in these declarations may be used by all 
procedures anywhere in the system, Many externals are 
defined as part of the NLS system? user programs have 
complete access to these. Since other procedures may access 
the same variable^ the user programmer must be very careful 
about changing their values. 

Simple Variables 5c3 

Simple variables represent one computer word, or 36 bits, of 

memory. Each bit Is either on or off, allowing binary numbers 

to be stored in words. Each word can hold up to five ASCII 

7*bit characters^ a single number, or may be divided into 

fields and hold more than one number, 5c3a 

Declaring a variable allocates a word in the computer to 
hold the contents of the variable. The variable name refers 
to the contents of that vord. One may refer to the address 
of that computer word by preceding the variable name by a 
dollar sign ($), 

For example, if one has declared a simple variable called 
"hum", one may put the number three in that variable with 
the statement: 

num • 3 J 

One may add two to a variable with the statemtnts 

num ^ num ■»■ 2 j 

one may put the address of num into a variable called 
addr with the statement? 

addr » $num j 

one may refer to predefined fields in any variable by 
following the name of the variable with a period, then the 
field name. For example, the fields RH and liH are globally 
defined to be the right and left half (18 bits) of the word 
respecttveiyr .e',g^, • 

nuro,LH «^ 2 f 
nuro.RH ^ 3 ? 
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Fields way be defined by the user with RECORD statements 
(described in section 5 of Part Five), AdditlonaXXy, you 
iTtay refer to system-def ined fields (e,g, RH), They divide 
words into fields by numbers of bits, so they may refer to 
any declared word. For example, the field "LH» refers to 
the leftwmost 18 bits in any 36«bit word. 

If you assign a full word to a field of n bits within a 
word| the right«»PR0stn bits will be assigned to the field 
in the destination wordr the rest of the destihation word 
will be untouched. 

If you assign a field with a word to a full word. It will 
be right'lustlf led within the destination wordi the 
remaining bits in the destination word (to the left of 
the assigned bits) will be set to zero. 

Declaring Simple Global Variables 5c3b 

DECLARE name ; 

"name" is the name of the variable, it must be all 
lower-case letters or digits^ and must begin with a 
letter, 

E.g, 

DECLARE XI J 

Optlonallyf the user ^ay specify the initial value of the 
variable being declared. If a simple variable is not 
Initialized at the program level, for safety it should be 
Initialized in the first executed procedure in which it 
appears, 

DECLARE name s exp j 

exp is the initial value of name, it may be any of the 
following; 

•• a numeric constant optionally preceded by a minus 
sign (•) 

» a string, up to five characters, enclosed in 
quotation marks 

» another variable name previously defined in a SET 
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statement (described below), causing the letter's 
value to be assigned 

Examples? 

DEC1,ARE X2s5; 

%X2 Contains the value 5% 
DECl^AEE x3s!"0UT"? 

%x3 contains the word OUT% 

DECLARE XXax4f 

%x4 has previously been declared in a SET 
statement% 

For?nal paraineters (passed to a procedure) are allocated as 

local simple variables # then initialized whenever the procedure 

is called, ivithin the called procedure, they should be treated 

as simple variables. 5c3c 

constants 5c4 

You may declare a (simple) variable to be a constant value with 

the statements 5c4a 

SET namel^exp i 

where names and expressions are as described above for 
initializing simple variables. 

Constants take no memory* fhey may be refered to just like 

simple variables? except the name must be preceded by a dollar 

sign ($), They may not be changed by the program. E,gt 5c4b 

after the declarations 

SET var » 4 J 
the assignment? 

num ^ Svar i 
will assign the value 4 to the variable num. 

Arrays 5c5 

Multi*word (one«dlmensional) array variables may be declared? 
computer words within them may be accessed by indexing the 
variable name. The index follows the variable name, and is 
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encXosec} in square brackets Ht The first word of the array 

need not be Indexed, The index of the first word is jpero, so 

if we have declared a ten element array named "blah": 5c5a 

blah is the first word of the array 
blahCl] is the second word of the array 
blahf93 is the last word of the array 

Declaring Global Array Variables 5c5b 

DECLARE nameCnuni] j 

n«m is the nu!Tiber of elements in the array if the array 
is not being Initialized, it must# of course, be an 
integer, 

E,g, 

DECLAPE SaiuClOJ ? 

declares an array na»e<3 »^am» containing tO elements. 

Optionally^ the user ?nay specify the initial value of each 
element of the array* If array values are not initialized 
at the prograin level* for safety they should be initialize^a 
in the first executed procedure in which the array is used, 

DECLARE f\9me » (nuroii nuin2f »,, 3 ? 

nuiiR is the initial value of each eieient of the array. 
The number of constants implicitly defines the number 
of elements in the array. They may be ahy of the 
constants allowed for slJsple variables. 

Note: there is a ohe*to»one correspondence between the 
first constant anci the first element/ the second constant 
and the second elemehtf etCt 

Examples I 

DECLARE numbss5(lf 2f 3) I 

declares an array named numbs containing 3 elements 
which are initialized such that: 

numbs = i 
numbs tU « 2 
numbs 1:23 * 3 
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DECLARE motiey3C10#$blah}f 

decXares an array named motley containing 2 
elements which are initialized such that? 

lotley a 10 

motley C13 s $blah = the address of the variable 
"blah" 



Text Pointers 

A text pointer is an LIO feature used In string manipulation 
constructions. It is a two-word entity wnich provides 
information for pointing to particular locations within textp 
whether in string variables or In NLS statements. 

The text pointer points between two characters in a 
statement or string. By putting the pointers between 
characters a single pointer can be used to roar}< both tbe end 
of one substring and the beginning of the substring starting 
with the next character^ thereby simplifying the string 
manipulation algorithms and the way one things about 
strings, 

A text pointer consists of two words? a string identifier and a 
character count. Assume you have declared a text pointer named 

pt refers to the first word of the text polntert The first 
wordf called an "stidi" contains three system-defined 
fields J 

St file •• the file number Clf an Ni.s statement) 
stastr •• a bit indicating strlngt not an nlS statement 
stpsid •* the psid of the statement; every statement has 
a unlgue number (psid) attached to It, 

The stld is the basic handle on a statement in LIO, it 
is Often usea sione. Since it is a single*word vaiue# It 
may be stored In a simple variable and passed easily 
between procedures i and Is used by many routines to 
specify a statement or string. 

If an stld Is used without being properly set* the 
run»tlme error message "fst entry nonexlstant" may 
result. 



5c6 



5c6a 



5c6b 
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ptCU refers to the second word of the text pointer. The 
second word contains a character counts with the first 
position being 1 (before the first character). 

For example f one mignt have the following series of 
assignment statements whicn fill the three fields of the 
first word and the second word with data^ with pt being the 
nmme of a declared text pointer: 

ptfStf ile «K f ilenoj 

%fiieno is a simple variable with a number in it% 
pt.stastr «, FALSE? 

%a statement, not a string! 

pt.stpsid ^ origin? 

tall origin statements have the psid ss 2f origin is a 
global variable with the value 2 In it% 

P V I 4. J. -imi' * f 

%the Word one after pt (i,e, the character count) gets 
1, the beginning of the statement% 

It is Important that stid^s he initialized proptrly to avoid 
errors. Text pointers ^^Y ^e Rjost easily initialized by 
setting then? in a find statement (see Section 6), 

Declaring Text Pointers 5c6c 

DECLARE TEXT POINTER pt | 

The names pit p2r pii p4f and p5 are globally declared and 

reserved for system use, 

strings Sc7 

String variables are a series of words holding text, when they 

are declared, the Jnaxiiiiuin nunfiber of characters is set. The 

first word contains the two globally defined fields! 5c7a 

^ •* the ipaxlffium number of characters the string can hold 
h "* the actual number of characters currently in the string 

The next series of words (as many as are reguired by tne 
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maximum string size) hold the actual characters r five per word^ 

in ASCII 7*bit code, 5c7b 

*str* refers to the contents of the string variable "str'V 

str refers to the first word of the string variable *Vstr"? 
typically this is only useful in combination with th© two 
fields «H" and «L«s 

str,M refers to the maximum declared length of the 
string variable "str" (an integer). 

str,Ii refers to the current length of the string stored 
m the string variable "str" (an integer). 

Declaring strings 5c7c 

The DECi^^^K STRING enables the user to declare a global 
strihg variable by initializing the string and/or declaring 
its maximum character length, 

TO declare a strings 

mchhm STRING nameCnumj f 

num is the maximum number of characters allowed for 
the string 

Since the maximum statement length is 2000 characters # 
you should not need to declare a string greater than 
2000 characters long, 

E.g. 

DECiABE STRING istrlng E1003 > 

declares a string named wlstring" with a maximum 
length of 1 00 characters and a current length of 
characters 

TO declare and initialize a string? 

1>eCI.^^E string name*" Any string of text" i 

The length 0* the literal string defines the maximum 
length of the string variable 



• 



Etg. 
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DECLAHE STRIWG roeSSagea"RED ALEHT"y 

declares the string message, with an actual and 
maximum length of 9 characters and contains the text 
"RED ALERT" 

REFs Referenced Variables 5c8 

Reference Declarations 5c8a 

After a simple variable has been declared, the REF statement 
can define it to represent some other variable, A 
referenced variable holds the address of another declared 
variable of any type, whenever the referenced variable is 
mentioned, LlO will operate on the other variable instead, 
as if it ^ere declared in that procedure and named at that 
point, 

This is useful when you wish a procedure to know about a 
multi^word variable, in procedure calls, you are only 
allowed to pass single»word parameters. If you wish a 
called procedure to use or operate on a text pointer# arrays 
or string* you way pass the address of that multi«*word 
variable. Then, in the called procedure, you must REF the 
formal parameter receiving that address, prom then on in 
the called procedure* when you refer to the REFed parameter* 
you are actually operating on the multi»"word variable 
declared in some other procedure to which the local REFed 
variable points* i,e, on the variable at the address 
contained in the REFed parameter. 

Example: 

If the simple variable "loc" in the current procedure 
has been pEFed and contains the address of the string 
"str** local to the calling procedure, then operations 
on loc actually operate on the string in str: 

*mes* «. *loc#j 

%mes gets the string in str% 
*loc* ^ "corpuscle"? 

%str gets the string "corpuscle"! 

Similarly* you cannot return multi-word variables from a 
called procedure. If you wish a procedure to return a 
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string, you must declare the string as a local in the 
CALLING procedure, pass its address to a PEFed variable in 
the called procedure. Then the called procedure can modify 
the string as if it were local (and return nothing). The 
modifications will be made in the actual string variable. 



Unreferencing REFed Variables 5c8b 




variable) , 



,g, if X has been REFed and holds the address of y: 



%z gets the Cbf^TEMfS of y% 
z .», «x * , , 

%z gets the ADDRESS of y% 

This construct might be nse.4, for example^ if one procfdufe 

\has' 'been /pass^'d ^the -address'' 'Of 'va'^ stTingf\ operates '-on' itV/;;^ , 
then wishes to pass (the address of) that string on to 
another procedure that it calls. 

This c^n be a tricJcy concept i it roay be worthwhile to review 
this section carei^uliy, 

REfing Simple Variebles 5«:8c 

once a sli^ple variable has been declared (as a global, 
local, or parameter)* it may be PEFed with the LIO 
declaration statement? 

REF var ? 

It will be a reference from then on In that procedure, and 
you must always use the ampersand to refer to its actual 
cohtentsi the address of the variable it references, 

Not^ that the REF statement does not allocate storage? it 
just sets an attribute of an existing variable. 
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It you wi3h to use a vatiabie that is not REFea as if it 
were REFed, enclose it in square brackets C3, E,g, assume 
the siffipie variable "astr" holds the address of a string 
variable but was MOT REFedj 

#Castr]* refers to the contents of the string variable 
whose address is in astri 

Note on Progranfiffling Style 5c8d 

YOU should always REF locals and parameters which hold the 
address of something to be accessed (even if that variable 
is only used to pass the address on to another procedure). 

Declaring Many Variables in one statement 5c9 

One may a^old Putting several individual declarations of 

variables in a series by putting variables of similar type. 

Initialized or notf in a list in one statement following a 

single DECIAREi separated by commas and terminated by the usual 

semicolon. Array and simple varibles may be put together In 

one statement. 5c9d 

examples? 

Declare x, ytioj, 2 s (it %, ^s)? 

DECLARE TEXT POINTER tPr Sf, p%i, Pt2 ; 

DECLARE STRING IstringClOO]* meSsage»«RED ALERT" | 

Declaring Locals 5cl0 

Program level declarations (DECLAf^E and REF) and procedures may 
appear in any or<Sert However, procedure level declarations 
(LOCAL and REF Inside a procedure) must appear before any 
executable statements in the procedure. The different types of 
variables may be declared in any order r but a variable must be 
declared before it can be REFed, SclOa 

Whenever possible, LOCALS Should be used instead of globals. 
It makes for a Cleaner program if you pass parameters among 
procedures rather than depend on global variables to 
transmit information. 

With one exception, a local variable declaration statement Is 

just the same as a global with the word '»LOCAL'* substituted for 

the word '»DECLAre», The one exception is that LOCAL 

declarations c^n not Initialize the variables, SclOb 
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ExafflPlesj 

LOCAl^ var, fXagv level £121 ? 
I.OCAL TEXT POINTER tp^ pt, sf J 
1.0CAI, STRING testClOO], outt2000J j 

m&n a procecJure is called by another proceduref the calling 
procedure may pass one»word parameters. The procedure receives 
these values in simple local variables declared in the 
PROCEDURE statement's paraffleter list, for examplef two locals 
will autOfT^atically be declared and set to the passed values 
whenever the procedure "procname" is called! 5cl0c 

CprocnaiRe) PROCEDURE Cvarlf var2 3 j 

van and vara wust not toe declared again In a LPCAt 
statement, They may, however # be REFed by a REF statement, 
as discussed above, and used throughout the procedure. 

The statement which calls procname may look liKei 

procnasie (locvar, 2) > 

varl will be initialized to the value of the variable 
»»locvar'v and var2 will get the value 2, 

Declaring Externals Sell 

Externals are declared just liice globals, with one exception, 

The word DECLARE must be followed by the word EXTERNAL. E,g, Sella 

SET EXTERNAL one»l# two'92 t 

DECLARE EXTERNAL a, bllOlr CsS j 

DECLARE EXTERNAL TEXT pOIUTER exptrl, exptr2 ; 

DECLARE EXTERNAL STRING exstrUOOJ ; 

REr specifications may not be external to the program, 5cllb 
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Accessing Registers 5cl2 

The user may access machine registers (the sawe length as other 
wordSf i,e, 36 bits) by naming thew with the declarations 5cl2a 

REGISTER naiTf^e a regnum ; 

or 
REGISTER namel^regnumj, name 2 =? re gnu ma i 

The declared names will then represent the registers to which 

they are attached, xon rnay then access or assign values to 

their content, on tenex, the user programmer may use the first 

seven registers, registers through 6, (Registers 7 through 

15 are reserved for system use,) E,g, 5cl2b 

REGISTER rO»0r Ti^i, r2a2# r3a3f r45!4# r5s5# r6s6 ? 

The names used in the above example are used most often by 
convention t 

Registers must be used very carefully! fhey are typically used 

when calling tEMEX asYS (see section 4), Many lilO constructs 

and procedures use the registers? you should assign their 

content to a variable immediately after the JSYS call it you 

wish to save it, 5cl2c 
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Section 4 J Statements 5d 

Introduction 5dl 

This section will describe some of the types of statements with 
which one can build a proceduret The term "expression" (often 
abbreviated to "exp") will be used in this sectionf and will be 
explained in detail in Section 5 (5e), 5dla 

Assignment 5d2 

In the assignment statement, the expression on the right side 

of the "«," is evaluated and stored in the variable on the left 

side of the statement. 5d2a 

var -» exp j 

where vat = any giobai, locax* referenced or unreferenced 
variable, 

one may maKe a series of assignments in one statement by 

enclosing the list of variables and the list of expressions in 

parentheses. The or<3er of evaluation of the expressions is 

left to right. The expressions are evaluated and pressed onto 

a stack? after all are evaluated they are popped from the stacK 

and stored in the variables, 5d2b 

Cvarlr var2f >,,) » (expli exp2f ,,,) j 

NaturailVf the number of expressions must eguaj, the nuiber 
of variables. 

Examples 

(a, b) • Cc+d, a»b3 

The expression c+d is evaluated and stacked, the 
expression a»b is evaluated and stacked, the value of a»b 
is popped from the stack and stored into b, and finally, 
the value of C4d is popped and stored into a. It is 
equivalent toi 

tempi ^ c+d J 

temp 2 ^. a»b ; . . 

b ^ temp2 j 
a :«. tempi ; '■ 
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One may assign a single value to a series of variables by 

stringing the assignraents together! 5d2c 

vari » var2 .^ var3 ^ exp ? 

The assignment win be made from right to left, varlf var2r 
and var3 will all be given the value of the expression. 

Example} 

a .,», b •. 1 

Both a and b wxii be given the vaiue zero. This type of 
staten^ent can be useful in initializing a series of 
variables at the beginning of a procedure, 

BUMP statement 5d3 

The BUMP statenient will add one to a variables 5d3a 

BOMP var t 

This is equivalent tos 

var w var + I j 

BUMP DOWN will subtract one froffi a variables 5d3b 

BUMP DOWN var j 

This is eguivalent toS 

var * var » 1 ? 

You may BUMP more than one variable in a single statements 5d3c 

BUMP varlf var2# var3,,,, ? 

or 
BUMP DOWN varif vara, var 3,,,, ? 

If statement 5d4 

This form causes execution of a statement if a tested 
expression is TRUE, if the expression is FAi»SE and tne 
optional ELSE part is present, the statement following the ELSE 
is executed. Control then passes to the statement Immediately 
following the iF statefsent, 5d4a 
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IF testexp THEN stateinent ; 

IF te$texp fHEN statement I ELSE statement2 ? 

The statements witfiin the IF statement can foe any statementf 
but are not followed by the usual semicolonj the whole IF 
statement is treated liKe one statement and followed by the 
semicolon, Sd4b 

■E:»g,,/ ■ ■ -■■ 5d4"r 

IF y«z fHEU y*»y+l ELSE y«,z ; 

In some cases, complex nested IFS may be simpler il rewritten 

as a CASE Stateinent, 5d4d 

CASE Statement 5d5 

This form is similar to the IF statement except that it causes 

one of a series of statements to be executed dependinq on tne 

result of a series of tests, 5d5a 

CASE testexp OF 

reiop exp i statement ? 
relop exp 5 statement j 
reiop exp : statement ; 

ENDCASE statement ? 

where relop a any relational or interval operator (>«# <# Sf 
IN, etc,) see Section 5 (5e3c) and (5e3d), 

The CASE statement provides a means of executing one statement 

out of many. The expression after the word "CASE" is evaluated 

and the result left in a register. This is used as the 

left-hand side of the binary relations at the beginning of the 

various cases. Each expression is evaluated and compared 

according to the relational operator to the CASE expression. 

If the relationship is TRUE, the statement is executed. If the 

relationship is FALSE, the next expression and relational 

operator will be tried, if none of the relations is satisfied, 

the statement following the word "ENDCASE" will be executed. 

Control then passes to the statement following the CASE 

statement 5d5b 

Note that the relop and expressions are followed by a colon, 
and the statements are terminated with the usual semicolon. 
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The word ENDCASE is not followea by a colon. In ENPCASE, 
the stateicent m&Y be left out •• thjs is the equivalent of 
having a l^Ulil. statement there; nothing will happen. 

Example; 

CASE C OF 

w a J %ex,ecyted if c « a% 

■ ■> 'bi ''lexecute^ ■■ if c > t>% 
ixt y) ^ (x+y^ x-y)r 
ENDCASE ^executed otherwlse% 
y » xf 

CASE Char OF 

e Ds %if char « the code for a digit% 

char ^ *1; 
» Uti %lf char » the code for an upper*case ietter% 

char « '0? 
ENDCASEi %otherwise nothing% 



Several relations snay foe listed at the start of a single casej 

they should be separated by commas, Tne statement wm be 

executed if any of the relations is satisfied, 5d5c 

CASE testexp OF 

reiop;...exp!, /state.pent j 

reiop exp, relop exp? statement f 

reiop exp, relop exp^ relop exps statement ? 

• ■ 
■■#,■■ 
endcaSE stateraent t 

Example? . 

CASE c or 

■^aaf.xdf ' ..%executed if csa' or ,c<d% 

- X 1^0 y I 

>bf *dt %executed if c>b or c»d% 

Cx#y) :^.. (X'»^yrx*y)? 
ENDCASE ^executed otherwlse% 

y ii» X f ■ ■ 

As a point of styie, the conditions of the CASE statement 

shoiald be put one level below the CASE statement in the source 

(text) file. The statement s elf they are wore than one line) 

may be put one level below the condition, 5d5d 
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LOOP statement 5d6 

The statement following the word "IjOOP" Is repeatediy executed 

until control leaves by means of some transfer Instruction 

within the loop, 5(|6a 

LOOP statement? 

where statement a any executafc>le LIO statement 

Example I 

LOOP If a>sb THEN EXIT bOOP ELSE a w a+1 J 

(It is assumed that a and d have been initialized before 
entering the loop.) 

The EXIT construction is described below, it is extremely 
important to carefully provide for exiting a loop, 

WHILE,,, DO statement 5d7 

This statement causes a statement to be repeatedly executed as 

long as the expression immediately following the word WHILE has 

a logical value of TRUE or control has not been passed out of 

the DO loop by EXIT LOOP c«3escribed below), 5d7a 

WHILE exp dO statement ? 

exp is evaluated and if TRUE tbe statement following the word 

DO Is executed? exp is then reevaluated and the statement 

continually executed until exp is FALSE, Then control will 

pass to the next statement « 5d7b 

For example! if you want to fill out a string with spaces 
through the 20th character position^ you couldi 

WHILE str.L < 20 DO »str* «- *str#, SP? %what's already 
there! then a space% 

Remember tbat the first word of every string variable has 
two globally defined fields: 

L •* actual length of contents of string variable 
M ** maximum length of string variable 

The ^HILE construct is equivalent tos 5d7c 



page 55 



&ARC*A|»P 4*OEC*7S 20J25 34G44 
ARC 34044 Hev, 5 DEC 75 uhB PtogTammers* Ovii4e 

Part Three: statements 



LOOP 

IF HOT exp THEl^ EXIT LOOP 
ELSE statement i 

UNTIL,, f DO stateinent sas 

This stateiuent is similar to the WHILE,,, DO statement except 

that tne statement following the DO is execute<l Until exp is 

TRUE, As long as exp has a logical value of FALSE the 

statement will be executed repeatedly, 5d8a 

UNTIL exp DO statement i 

Example I 

UNTIL a>b DO a ^ a+l ? 

The UNTIL construct is equivalent toi 5d8b 

LOOP 

IF exp THEI^ EXIT LOOP ELSE statement r 

DO,.,UMTIL/DO,»,i^HILE Statement 5a9 

These statements are like the preceding statementSf except that 
the logical test is made after the statement has been executed 
rather than before, 5d9a 

DO statement Ul^JT^L exp? 

DO statement WHILE exp? 

Thus the specified statement is always executed at least once 
(the first time, before the test is made), For example, this 
D0,,,UNTIL8 5d9b 

DO array Cvarl ■^ UNTIL (var !» var • U » ; 
and this DD,.,NHILEi 5d9c 

DO arraycvar] ^ o while (var :» var • 1) > j 

are both equivalent to? 5d9d 

LOOP 

BEGIN 

array Cvarl ^ o t 
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IF (var ;:? var * 1) s? tHEH EXIT LOOP j 
END? 

FOR»,,DO Staterpent 5dl0 

T^*e FOR statement causes the repeated execution of the 

statement following "D0« until a specific terminal value is 

reached, 5dlOa 

FOR var UP UNTili relop exp DO statement? 

(UP will be assumed if left out,) 

FOR var DOWN until relop exp DO statement; 

where 

var » the variable whose value is incremented or 
decremented each time the FOR statement is 
executed 

relop « any relational operator (described in 5e3c) 

exp 5? when combined with relop# determines whether 
or not another iteration of the FOR Statement 
will be performed. It is recomputed on each 

iteration. 

E.g. FOR i UP UNTIL > 7 DO d \. a + tti] i SdlOb 

Optionaliyf the user may initialize the variable and maY 

increment it by other than the default of one, SdlOc 

FOR var ^ expl u? exp2 untiIi relop exp3 do statement? 
FOR var «, expl down €xp2 UNTit relop exp3 DO statement? 

where ■ 

expl -9 an optional initial value for var t It expl Is not 
specifiedf the current value of var is used, 

exp2 a an optional value by which var will be incremented 
(if UP specified) or (decremented (if DOWM specified), if 
exp2 is not specified, a value of one will be assumed, 

Mote that exp2 and exp3 are recomputed on each iteration. 

Example; 
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FOR K « n UP K/2 UNTIL > nt*3 DO XCK] ^ k? 

is equivalent to 

K - n? 
LOOP 

BEGIN 

IF k >I!)*3 THEN EXIT LOOP? 

xCK] ^ K? 

i^fDJ 

Be:GIN,^,END statement 5dH 

The BEGIN,, tEJ^D construction enables the user to group several 
statements Into one syntactic statement entity, A 8i:GIM,,,end 
construction of any length is valid where one statement is 
required, Sdlla 

BEGIN statement y statement ; ,,, F.ND t 

Examples 

IF a >». h*c THEN , 
BEGIN 

C^d+5j 

END %no semicolon here because an LIO 

statement here wouldn't have onei see 5d4% 

JCrf i|J O IL , , 

BEGIN 

• .b*!...d + 2 J . • 

c«,b#d*7; 

END; %this semicolon terminates the entire IF 
.statement% ' 

Note the use of KLs file structure to clarify the logic arid 
separate the blocks. Blocks should always be put one level 
below the statement of which they are a part, 

EXIT Statement 5dl2 

The EXIT statement transfers control (forward) out of CASE or 

iterative statements, A CASE statement can be left with an 

EXIT CASE statement. All of the iterative statements (LOOP, 

WHILE, UNTIL, 0Of FOR) can be exited by the EXIT LOQP 

statement, EXIT and EXIT LOOP have the same meaning, 5dl2a 
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EXIT WQP nm 
EXIT CASE num 



or EXIT nuff» 



where num is an optional integer t The optional nurober 
(nunt) specifies the number of lexical levels of CASE or 
iterative stateffients respectively that are to be exited 
Ce,g, If loops are nested within loops). If a number is 
not given then t is assumed, 

ExamplesT" ■ ■ ■ 

LOOP 

BEGIN 

IF test THEn EXIT; 

%the EXIT will branch out of the 1*00?% 

Ciit ™ M |i 

UMTiIi something DO 
BEGIN 

WHILE test! 00 

lF*test2 THEN EXlTj 

%the EXiT will branch out of the i^HlLE% 

• » • » « f f f 

t f 9 f * * « « 

END; 



0MTIL something DO 
BEGIN 

• « .»' 1 1 i f ' ■ 
WHILE testi 00 
BEGIN 

IF test2 THEM EXIT 2; 

%the EXIT 2 will branch out of the until% 

•*•#••«§ 
ENDl 

i 9 f « 9 « 9' « 



END; 
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CASE exp or 
sssoffiethingj 
BEGIN 

IF*test'i:HEN EXIT CASE; 

%the EXIT will branch out of tue GASE% 

» f « t • ■* •'# 

END; 

« ;* « • f t' t • 

REPEAT Statement 5dl3 

The REPEAT statement transfers control cbacKward) to the front 

of CASE or Iterative statements. The optional nuRiber has the 

saree weaning as In the exit statement, REPEAT ana REPEAT CASE 

have the saire meaning, 5dl3a 

REPEAT hQQP nm 

REPEAT CASE nUffi (exp) or REPEAT num (exp) 

If an expression Is given In parentheses with the REPEAT CASE, 

then it is evaluated and used in place of the expression given 

at the head of the specified CASE statement. If the expression 

Is not given, then the one at the head of the CASE statement is 
reevaluated, 5dl3b 

Examples! 5dl3c 

CASg; expl Of 
asomethlngs 
BEGIN 

iF*testl THEN REPEAT! 

%PePeAT with a reevaluated expl% 

IF*test2 THEN REPEAT(exp2) ? 
%PePeAT with exp2% 

END? 

ENDCASE J 
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LOOP 

BtQXn 

IF*test THEN REPEAT liOPPl 

%REPEAT LOOP will go to the top of the LoOPt 

DIVIDE statement 5dl4 

The divide statetnent perroits both the quotient and remainder of 
an integer division to be saved. The syntax for the divide 
statement is as follows? 5dl4a 

DIV expi / exp2 , quotient # remainder ? 

Quotient and remainder are variable names in which the 

respective values will be saved after the division, 5dl4b 

E.g. 

DIV a / bf af r j 

a will be set to a/b to the greatest integer with r 
getting the remainder 

Floating point calculations are described in Part FivCf Section 

4, 5di4c 

PROCEDURE Ckhh Statement 5dl5 

ProcecSure calls direct program control to the procedure 

specified, A procedure call occurs when the name of the 

procedure is followed by parentheses, if the procedure 

requires that arguments be passed^ they should be included in 

the parenthesesi separated by commas, SdlSa 

procname (enp, exp, i^^^} t 

where procname « the name of a procedure 

exp != any valid LiO expression (explained in Section 5), 
Tf>€ set Of expressions separated by commas is the 
argument list for the procedure. 

The argument list consists of a number of expressions separated 
by commas. The number of arguments shoul«3 equal the number of 
formal parameters for the procedure. The argument expressions 
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are evaluatea in oraer from left to right, Each expression 

(parameter) niust evaluate to a one^word value. The values win 

be assigned to the formal parameters of the called procedure, 5dl5b 

To pass an array, text pointer^ string, or any multi*word 
parameter* the programmer may pass the address of the first 
word of the variable, then REF the receiving local in the 
called procedure^ 

For exaroplet one may pass an stid directlyt but to pass a 
text pointer, you m^st pass th® address of tn^ text pointer 
and REF the receiving parameter^ Remember that a dollar 
sign C$3 preceding a variable represents the address of that 
variable. 

The procedure may return one or more values. The first value 

is returned as the value of the procedure call. Therefore, if 

only one value is returned* one might says 5dl5c 

a « proc (b) i 

in this context, the procedure call is an expression. 

If more than one value is returned by the called procedure* one 
must specify a list of variables in which to store them. The 
list of variables for multiple results is separated from the 
list of argument expressions by a colon. The number of 
locations for results neea not equal the number Of results 
actually returned, if there are more locations than results, 
then the extra locations get an undefined value. If there are 
more results than locations, the extra results are simply lost. 
The first RfTURf^l value Is still talcen only as the value of the 
procedure call» SdlSd 

var w procname (exp, exp, ,,, : var, var, ttt) j 

Exampie; 

If procedure "proc** ends with the statement 

retuRm Ca,b,c) 

then the statement 

q ^ procc Jns) J 

results in Cg,r,s) ^ ca,b,c). 
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A procedure call may just exist as a statement alone without 

returning a value. Not all procedures require parameters^ teut 

the parentheses are mandatory in order to distinguish a 

procedure call froi other constructs, 6dl5e 

E,g, idaOi 

If a block of instructions are used repeatedly? or are 

duplicated in different Sections of a program/ it is often wise 

to maKethera^ a separate procedure and siroply call the procedure 

when appropriate, 5dl5t 

It is considered good style to "modularize" the functions of 
your program as much as possible* where each procedure 
represents a function which will be performed no matter 
which procedure called it t This implies very lisilted use of 
global variables and careful definition of the procedure 
mxertacet 

Procedures should not be made too longi nor have cowplex 
nested loops, often breaKing the code into a number of 
shorter procedures will make the program clearer and easier 
to debug, 

A procedure way recursively call itself. Each call will have 

Its own unique set of local variables. This may be useful if a 

procedure Is built to handle a general case as well a$ a 

specific case or number of cases. The general case may call 

that same procedure for the specific case after some 

manipulations, SdlSg 

A great many procedures are part of the Uh^ system and are 
available to your programs t A list of them is available in the 
file <NLS,XPROCSf> or <ms,SYSGDf>, SYSGD lists llnKs to the 
Source code* so that you can examine the procedure in detail to 
see just what It expects as arguments and what it returns, 5di5h 
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RETORN Statement 5dl6 

This statement causes a procedure to return control to the 
procedure which called it, optionally, it may pass the calling 
procedure an arbitrary number of results. The order of 
evaluation of results Is from left to right, 5dl6a 

RETURN ; 

RETURN (expf exp, ,,,) ; 

E,g, 5dl6b 

RETURN (TRUE, afb) f 
RETURN C getnmfCstid) ) j 

GOTO Statement 5dl7 

Any statement may be labeled; one puts the desired label (a 
string of lower case letters and digits) in parentheses and 
followed by a colon at the beginning of a statement, Sdl7a 

(label) s statement y 

E,g, Sdl7b 

(there) I a ^ b f c ; 

GOTO provides for unconditional transfer of control to a new 
location, 5dl7c 

GOTO label ? 

E,g, 5dl7d 

GOTO there ; 

GOxO statements maKe reading and debugging your program 
difficult and are not considered good style? they can usually 
be eliminated by use of procedure call$ and the iterative 
statements, 5dl7e 

NULL Statement 5dl8 

The NULL statement may b® used as a convenience to the 

programmer. It does nothing, 5dl8a 

Null j 
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Exaniplei 

CASE exp OF 

50, si J NULL I 
ENDCASe y^U 

JSYS Call and Assembly Language statement Sdx9 

The use of these capabilities should be limited to system 

programmers. Assembly language code malces user programs 

difficult to uhderstand and to maintain as the executive 

underlying nhS changes over time, HO procedures are available 

to accomplish roost of the tasks one might want to do with a 

JSYS, System programmers should refer to the TEMEX as^S manual 

for a description of the available JSYS's, 5dl9a 

Assembly language statements may be included in the LIO code by 
Preceding the statement with an exclamation*point (i), E.g, 5dl9b 

J PUSH s#3fn J 

A TeneX jSyS may be invoked with a statement similar to the 

procedure call statement? the name of the jSYS must be preceded 

by an exclamation*pointi 5dl9c 

iJSYSNAME (regl, reg2,^/.) ? 

The arguments in the parentheses are evaluated and loaded into 

the registers before the jSYS is Invoked, The first argument 

will be put in register one, the second in register two, etc. 

Up to eight arguments may be given, Sdl9d 

Like a procedure call, multiple results may be received. They 

will be taken in order from the registers, (See <13510,3c> for 

a description of user JSYS calls, 5dl9e 



>ome vJSYS return to the assembly-language line of code (not the 
ilO statement) one beyond the normal return location, With 
luch JSYS, you may use the SKIP construct to test If it has 
lone soj 



IF SKIP tjsYS(argi,,,r> theni »f ; 

m using SKIP, you may not reCelve multiple results directly, 

but must read the registers into globals (see 50i2), 5dl9g 
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Section 5 J Expressions 5e 

Introduction 5ei 

This section will describe the composition of the expressions, 
which are an integral part of many of the statements described 
in section 4, 5ela 

Priffiitives 5e2 

Primitives are the basic units which are used as the operands 

of Lio expressions. There are many types of elements that can 

be used as hlO primitives ; each type returns a value which is 

used in the evaluation of an expression, 5e2a 

Each of the following is a valid primitives 5e2b 

a constant Csee below) 

any valid variable nasief referlng to t^e contents (of %he 
first wordr if not indexed) of that variable 

the contents of a string variable, refered to as #var» 

a dollar sign ($) followed by a variable name f referlng to 
the address Of tne variable 

a procedure call which returns at least one value 

the first (leftmost) value returned is the value of the 
procedure call? other values nsay be stored in other 

variables as described in Section 4, 

an assignment (see below) 

classes of characters; described in section i of Part One 

MIN (exp, exp# ,,,) the Biniitiui of the expressions 

MAX Cexpr exp# ,,,) the maximum of the expressions 

TRUE has the value I 

fAiSE has the value 

VALUE (astring) given the address of a string containing a 
decimal nuffiberf has the value of the number 
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VALUE (astrlng* num) given the address of a string 
containing a number and the base ot that number # has the 
value of the number (aliows other than base»ten numbers) 

READC (see below) 

CCP05 (see below) 

FIND 

used to test text patterns and load text pointers for use 
in string construction (see Section 6) j returns tbe value 
TRUE or FALSE depending on whether or not ail the string 
tests within it succeed, 

POS 

POS textpointeri reiop textpointer2 

may be used to compare two text pointers. If the POS 
construction is not used# only the first words of the 
pointers (the stld's) will be compared. If a pointer is 
before another* it is considered less than the other 
pointer, 

Efg, 

POS ptl = pt2 
POS first >ss last 

Constants 5e2c 

A constant may be either a number or a literal constant. 

There are several ways in which numeric values may be 
represented, A sequence of digits alone (or followed by a 
D) is interpreted as base ten, if followed by a B then it 
is interpreted as base eight, A scale factor may be given 
after the B for octal numbers or after a D for decimal 
numbers. The scale factor is equivalent to adding that many 
zeros to the original number. 

Examples: 

64 a lOOB = 1B2 

i44B a 100 3 1D2 
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LitsraXs may be ysed as constants as they are represented 
internally by nymeric values. The following are valid 
literal constants; 

•any single character preceded by an apostrophe 

etQf 'a represents the code for 14iB, 

•the following synonytns for comionly used characters: 

ENDCHR •'» endcharacter as returned by ReADC 

SP ■•• space 

hhl — fenex's version of altmode or escape (st33B) 

CR •* carriage return 

LF •• line feed 

EOh *- Tenex EQh character 

TAB •• tab 

BC •» backspace character 

BK -• backspace word 

Cg •- center dot 

CA •• command Accept 

CD •*• Comaiand Delete 

Assignnients 5e2d 

^n asslgnBent can be used as a value in an expression. 

The form a *. fo has the effect of storing b into a and has 
the value of b as the value of the asslgnKentt 

Another fori« of the ass Igni^ent statement ist 

.a t« b . . ■ ■ 

This will store b into a* but have the old value of a as 
the value of %he assignment when used as a priaitlve in 
an expression. 

For exa!tpie# 

b. ^.. ,Ca , i'W b } ' J' 

The vaiue of b win be put in a, 'The assignment win 
get the old value of ar which is then put in b. This 
transposes the values of a and b, (The parentheses 
are not really necessary,) 

READC • ENDCHR 5e2e 
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The primitive READC is a special construction for reading 
Characters trom HhS statements or strings. 

A Character is read trom the current character position 
in the scan direction set by the last CCPOS statement or 
string analysis Finn stateitient or expression, CCPOS and 
FlMD are explained in detail in section 6 of this 
docuRient, 

Attempts to read off the end o| a string in either 
direction result in a special "endcharacter" being 
returned and the character position not being iRoved, 
This endcharacter is included in the set of characters 
for which system mneumonics are provided and may be 
referenced by the identifier »ENDGHR«\ 

For exairiplef to sequentially process the characters of 
a strings 

CCPOS #str*? 

UMTIL (Char » READC) a EMDCHR DO proCess (Char) ; 

(Note; READC inay also be used as a statement it It is 
desired to read and simply discard a character), 

CCPOS 5e2f 

When used as a primitive, CCPOS has as its value the index 
of the character to the right of the current character 
position, if str « »tgiarp"» then after CCPOS *str#f the 
value of CCPOS is I and after CCPOS SE(*str*) the value of 
CCPOS is 6 (one greater tl^an the length of the string), 

CCPOS is fflore comnioniy used as a statement to set the 
current character position ipr use in text pattern matching. 
This is discussed in detail In section 6, 

CCPOS fpay be useful as an index to sequentially process the 
first n characters of a string (assumed to have at least n 
characters). 
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Example? 

CCPOS SFC#str*)f 

%CCpOS now has the index value of one, the front of 
the strlng% 
llNtlli CCPOS > n DO processCREADO? 

%REApC reads the next character and increments 
CCPOS% 

Operators 5e3 

Primitives may foe coirbined with operators to for^ expressions » 
Four types of operators will fee described here; arithmetiCf 
relational # interval # and logical. 5e3a 

Arithmetic Operators 5e3b 

i- (in front of a number) ■»* positive value 

* (in front of a number) •»• negative value 
4. ■*• addition" 

w «* subtraction 

♦ ••multiplication 

/ ••Integer division (remainder not saved) 

MOD •• a MOD b gives the remainder of a / b 

,V •• COR) a ,¥ b SB> bit pattern which has I 's where either 
a or b contains 1# elsewhere 

,X •• CXOR) a iX b «> bit pattern which has I's w^ere either 
a holds I and b contains Or or a contains and b contains 
if elsewhere 

,A •• (AND) a ,A b K> bit pattern which has I's where both a 
ind b contain it elsewhere 

Relational Operators 5e3c 

A relational operator is used in an expression to compare 
one quantity with another. The expression is evaluated for 
a logical value, if true# its value is if if false, Its 
value is 0, 
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operator 


Meaning 
eciuaX to 




Example 
4+1 = 3+2 




:3 




(TRUKr »1) 


« 




not equal to 




6#8 


imm» -u 


< 




less tiian 




6<8 


(TRUEf «1) 


<S 




less ttian or 












equal to 




8<a6 


iWkhSEf 9Q) 


> 




greater than 




3>8 


(FALSE, «0) 


■>s 




greater tban 


or 










equal to 




8>»6 


(TRUE, si) 


NOT 


<other»reiatlonal 


•operator> 












6 NOT > 8 


(TRUE, s?l3 



Interval Operators 5e3d 

The Interval operators perffjit one to check: whether the value 
ot a priffiitive falls in or out of a particular interval, 

IN (priJRitivef primitive) m [primitive, primitive) 

The value is tested to see whether or not it lies within a 
particular interval, E^Ch side of tn® interval may be 
"Open" or "closed'*. Thus the values which deterinlne tt\e 
boundaries may be included in the interval (by using a 
square bracKet) or excluded (by using parentheses), 

Example J 

X jn 11,100) 

.is the same as 

(X >5i) hm (X < 100) 
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Logical Operators Se3e 

Every numeric value aiso nas a logical vaXute, A nuroerlc: 
value not equal to ?;ero has a logical value of TRUE? a 
nu«)eric value equal to zero has a logical value of FALSE, 



a OP fo m. TRUE if a = TRUE or if b a TRUE 
»B FALSE if a » FALSE and if to » FALSE 

AND 

a AND b s; TRUE if a s TRUE and if b » TRUE 
= FALSE if a s FALSE or if b » FALSE 

NOT 

NOT a « TRUE if a =5 FALSE 
« FALSE if a s TRUE 

Expressions 5e4 

introduction 5e4a 

An expression is any constantf variable# special expression 
foriRf or combination of these joined by operators and 
parentheses as necessary to denote the order in which 
operations are to be performed. 

Examples of assigning an expression to a variable! 

var - Or 

var • var + 2 ? 

var ^ PqB ptrl >« ptr2 j 

var w Ca > b) qB (a IW Ccr dj ) j 

Liberal use of parentheses is highly recon^raended. 
Special Lio expressions are: 

• the FIND expression which is used for string 
ffianipulationf and 

• the conditional IF and CASE expressions which may be 
used to give alternative values to expressions depending 
on tests made in the expressions. 
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Expresstons ^re used where the syntax requires a value, 
While certain of these for»s are similar syntactically to 
LlO stateroentSf when used as an expression they always have 
values (see below). 

Order of Operator Execution^* Binding Precedence 5e4b 

The order of perforroinq Individual operations within an 
equation is determined by the hierarchy of operator 
execution (or binding precedence) and the use of 
parentheses. 

Operations of the same heirarchy are performed front left to 
right in an expression, operations in parentheses are 
perforraed before operations not in parentheses. 

The order of execution of operators Cfrow first to last) is 
as followsi 

unary ^# unary + 

• V, .X 
*>■,/, ,MOP 

relational tests (e,g,f >*y <»# ># <f ??# #/ IN, OUT) 

NOT relational tests ce,9,, l^OT >) 

nm 

■■. ■■.AND ■ ■ 

OR 

conditional Expressions 5e4c 

The two conditional constructs (IF and CaSe) can be used as 
expressions as well as stateients, As expressions# tl^ey 
inust return a value, 

IF Expressions 

IF testexp THEi^ expi EhSE exp2 
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testexp is tested for its logical value. If testexp Is 
TRUE then expl will be evaluated. If it is FALSE, then 
exp2 is evaluated. 

Therefore* the result of this entire expression is EITHER 
the result of expl or exp2, 

Exampl^i, 

y «^ IF X Illti,31 THEH X ESSE 4 y 

%if X ss 1, 2r or 3, then y^xi otherwise y«.4% 

CASE Expression 

This fortn is similar to the above except that it causes 
any one of a series of expressions to be evaluated and 
used as the result of the entire expression, 

CASE testexp OF 

reiop exp : exp ? 
relop exp s exp ? 
relop exp : exp ; 

* 

ENDCASE exp 

where relop = any relational or interval operator (>s, 
<, ;:, IN, etc, see above (5e3c) and (5e4d) 

in the above, the testexp is evaluated and used with the 
operator relops and their respective exps to test for a 
value of TRUE or FALSE, If TRUE in any instance, the 
companion expression to the right of the colon is 
executed and taken to be the value of the whole 
expression, A value of FALSE for all tests causes the 
next relop in the CASE expression to be tested against 
the testexp. If all relops are FALSE, the ENDCASE 
expression is taken to be the value of the whole 
expression. 

Note that ENDCASE cannot be null? it must have a value, 

AS with the CASE statement, any number of cases may be 
specified, and each case may include more than one reiop 
and expression, separated by commas. 
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Exafflplei 



y ^ ChSl X OF 
<3r xf ly 
s3f s4: x+2f 
sSs X? 
ENDCASE X#2| 



Value of 


X 


vaiu^ 0^ y 




*•*»•»•'■ 


«* i# ■#■ «» 'i* «* '# •»'■'•> » 


2 




3 


3 




5 


4 




6 


■5 




^ •■ 


6 




12 



String Expressions 5e4d 

LlO also provides several expression forms whlcli are used 
for string manipulation and evaluation, Tn^se are discussed 
in section 6 ol this docuifient, When using string 
raantpulatton statement foriRs as express ions # par entheses may 
be necessary to prevent ambiguities, 
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Section &• string Test and Manipulation 5f 

Introduction 5fi 

This section describes statements which allow complex string 
analysis and construction. The three basic elements of string 
manipulation discussed here are the Current Character position 
(CCPOS) and text pointers which allow the user to deliinit 
substrings within a string (or statement)! patterns that cause 
the systew to search the string for specific occurrences of 
text and set up pointers to various textual elementSf and 
actual string construction, 5fla 

current character Position (ccPOS) 5f2 

The Current Character Position is similar to the f^hS Cl^ 

(Control HarKet) in that it specifies tne location in the 

string at which subsequent operations are to begin. All j^lO 

string tests start their search from the Current Character 

position, in content Analyzer prograis, it is initialized to 

the BEGIil^lNa OF EACH NEfei STATEMENT. For each new statement, 

the scan direction is initialized to left TO RIGHT, It is 

moved through the statensent or through strings by find 

expressions. It may be set to a particular position in a 

statement or string by the LIO statement! 5f2a 

CCPOS pos J 

pps is a position ^n a statement or string that way be 

expressed as any of the followlngi 5f2b 

A previously declared and set text pointer* 

If a text pointer is given after CCPOSf then the 
character position is set to that location, A text 
pointer points between two characters in a string, 

e,g, CCPOS ptl ? 

String Front •» left of the first character 

SF(stspec) 



when sF is s 
character of 
by stspec. 



pecitiedr CCpOs will be set before the first 
the statement or string variable specified 
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stspec is a string specification that may be expressed as 

m an stid C6»gf the tirst computer word of a 
previously declared text pointer )# or 

• a previously declared string naifie enclosed in 

a s t e r 1 S'K s « 

Examples; 

CCPOS SFCPtl) ? 

%ptl is a text pointer! 
CCPOS sr(stid) I 

%stid is an stld% 
CCPOS SFC«str*) ? 

Istr is a string% 

String End *• ri<Jl^t of the last character 

SE( stspec) 

When sE is specified scanning will taice place froni rig^t 
to leftr and CCPOS will be set after the last character 
of the statement or string variable specified by stspec, 

h string (♦stringnaroe*) is given alter CCPOSt The position 
is rooved to tbe beginning ol that string, 

indexing the stringnaine (fey specifying Cexpl) simply 
specifies a particular position w|thinthe string, fhws 
#str«C3} puts the Current Character Position between the 
second and third characters of the string "str". If the 
scan direction is left to rig*^t/ then the third character 
will be read next, if the direction is right to leftf 
then the second will be read next, 

E,g, 

CCPOS #str»C33 t 

If no indexing is given, then the position is set to the 
left of the first character in the string. This is 
equivalent to an Index of 1, 

E,g, 

CCPOS' tstr# t 
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means the same as 
CCPQS SF(#str#)? 

Setting the current character position with the CCPQS statement 
also sets the scan direction to forward (left''to»right)f except 
if the SE construct is used, 5f2c 

riUD Statement 5f3 

The FIRID statement specifies a string pattern to be tested 

against a statement or string variable^ and text pointers to be 

manipulated and set# starting from the Current Character 

Position, If the test succeeds the character position is moved 

past the last character read, if the test fails the character 

position is left at the position prior to the FIMD statement. 

The values of text pointers set in the statement prior to the 

failing element will remain as set? otners of course will not 

be changed, 5f3a 

FIND pattern ; 

FINDS way be used as expressions as well as free*standing 

elements. If used as an expression! for example in IF 

statements, it has the vilUe TRUE if all pattern elements 

within it are true and the value FALSE If any one of the 

elements is false, 5f3b 

F.g, 5f3c 

IF FI?ID pattern THEN ,,, j 

It is good practice to use FIND as an expression with the 

appropriate error conditions if the FIND fails. If the FIND 

fails # text pointers may not be set as expected, 5f3d 

FIND Patterns 5f4 

A string pattern may be any valid combination of the following 



logical operators! testing arguments^ and other non*testing 
parameters (note the Identity with Content Analyzer Patterns)? 



5f4a 
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Pattern Matching Arguments*- 5f4fct 

(each of these can be TRUE or FALSE) 

string constantf e,g, "ABC" 

or any character, preceded by an apostrophy 

It shoulcJ be noteci that if the scan direction is set 
right'^towielt the string constant pattern should foe 
reversed^ In the above example, one would have to 
search for "CBA". 

Any of the system defined Mnemonics r as described in 
the last section C5e2c)# such as "SP" or "CP", are 
also valid, 

character class 

looK for a character of a specific class? if found, s 
TRUE, Otherwise FALSE, 

Character classes: 

CH »• any character 

L,-»* , lowercase''' or uppercase'. letter 

UL •« uppercase letter 

LL '■■*■'• l'0,wercase letter 

D •' digit 

LD *» lowercase or uppercase letter or digit 

nw *•» not a letter or digit 

ilLD»* uppercase letter or digit 

LLD •* lowercase letter or digit 

PT •• printing character 

m *• nonprinting character 

Example'? ■ ' 

char ^ hd 

is TRUE if the variable char contains a value 
which is a letter or a digit. 

(elements) 

look for an occurrence of tf*e pattern specified by the 
elements, if found* 5s TRUEf otherwise FALSE, 
Elements pay be any pattern? the parentheses serve to 
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group the elements so as to be treated as a single 
element in any of the following elements, 

•element 

TBUE only il the string constant or character class 
elentent following the dash does not occur, 

not element 

TRUE only it the eieraent or group of eiewents 
following the NOT does not occur* 

Celementsl 

TRUE if the pattern speciatied by the eleffients can be 
found anywhere in the remainder of the string, 
elements way be any pattern; the sguarebrackets also 
group the eleinents so as to be treated as a single 
eleiient. It first searches from current positiont if 
the search falledf then the current position is 
incremented by one and the pattern is tried again, 
incrementing and searching continues until the end of 
the string. The value of the search is faIiSE if the 
testing string entity is not matched before the end of 
the string is reached, 

HUM element 

find (exactly) the specified number of occurrences of 
the element, 

E»'gt 

3 (iO 3 means three letters or digits 

nmt $ HUM2 element 

Tests for a range of occurrences of the element 
specified. If the element is found at least NUMl 
times and at most MUM2 timesf the value of the test is 
TRUE. 

Either number is optional* The default value for 
NUPl is zero. The default value for MUM2 is 10000, 
Thus a construction of the form »'$3(CH)« would 
search for any number of characters (including 
zero) up to and including three. 
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Examples' 

2$4(UL) »- from two to four upper-case letters 

$10(SP) "^ up to ten spaces 

!$(*,) *- one or rpore periods 

ID = user^laent 
ID # user-ident 

if the string being tested is the text of an nhS 
statement then ident of the user who created or last 
edited the statement is tested by this construction; 
if CCPOS is in a string, you will get the error 
"string treated as statement" 

FT var 

TFUE if the variable holds a value of TRUE (non-^zero), 

SINCE datim 

if the string being tested is the text of an NLS 
statements this test is TRUE if the statement was 
created or modified after the date and time (datiro, 
see below) specified, 

BEFORE datim 

if the string being tested is the text of an fihS 
statement, this test is TRUE if the statement was 
created or modified before the date and time (datim, 
see below) specified. 
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Acceptable dates and times follow the torms permitted 
by the TENEX systerp's IDTIH JSYS described in detail 
in the TENEX JSYS manual. It accepts "most any 
reasonable date and time syntax," 

Examples of valid dates i 

i7»APR«7o 

AI'R*17*7 

APR 17 70 

17 APRIL 70 

17/5/1970 

5/17/70 

APRIL 17, 1970 

Examples of vali<3 times (zero assumed if time left 
out)s 

1:12:13 

1234 

1234:56 

1 :56AM 

l:56»EST 

1200NQON 

16:30 (4:30 PM) 

12:0O:O0AH (midnight) 

ll:59:59AM*EST (late morning) 

12:OOj01AM (early morning) 

Examples: 

BEFORE (MAR 19r 73 16:49) 
SINCE (25t'JUL"73 2130:00) 

These may not aPPear in Content Analysis patternSf put are 
valid elements in FIND statements in any programi 

*stringnaroe# 

the contents of the string variable 

BETWEEN pos pos (element) 

Search limited to between positions specified, pos is 
a previously set text pointer! the two must be in the 
same statement or string, scan character position Is 
set to first position before the pattern Is tested 
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(This is not an unanchored scan unless square brackets 
are used within the parentheses,), 

E,g, 

BEXMEEM ptl Pt2 C2D C.J mP) 

togicaX operators** 5t4c 

These cowblne and deiimit groups of patterns » Each coinpound 
group is considered to be a single pattern with the value 
TRUE or FALSE, The Character position will be reset to Its 
position before encountering the group before a new group Is 
tested. Any text pointers set within a test pattern before 
It fails will retain their new values, (see examples below,) 

/ 

AND 
OR 

These logical concatenators bind in the order in which 
they are listed, l,e, 

a / b AND c 

ffieans the sairie' as 
(a / b> mx> c 

other Elements*** 5f4d 

These do not involve testsi rather^ they Involve some 
execution action. Th^y are always TRUE for the purposes of 
pattern matching tests. 

These may appear in simple content Analysis Patterns? 



set scan direction to the left 

In this casef care should foe taken to specify 
patterns in reverse, that is in the order which the 
computer will scan the text. 



set scan direction to the right 
TRUE 
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has no ettecty it is generally wsea at tne end of OR 
when a value of true is desired even if all tests 

£ a i 1 9 

EN0CHP 

Attempts to read off the end of a string in either 
direction result in a special "endcharacter" feeing 
returned and the character position is not moved, 
T^^is endcharacter is included in the set of characters 
for which systeni fflneumonics are provided and »ay be 
referenced hy the Identifier "EWDCHg"t 

These lay not appear in simple content Analysis FatternSf 

but way in riNo statements: 



pos 



pos is a previously set text pointer # or an SE(pos) or 
SfCpos) construction. Set current character position 
to this position, if the Be pointer is used* set scan 
direction from right to left, if the Sr pointer is 
usedf set scan direction trom left to rig^tt. 



E,g, 



FIND xi tsets CCPOS to position of previously set 
text pointer x% 



ID 



store current scan position into the textpointer 

specified by the identifier 

b%t:K ^P the specified text pointer by the specified 
nii!i^ber imn) of characters. Default value for NUM is 
one. Backup is m the opposite direction of the 
current scan direction, 

FS var 
fR var 

FB will set the variable to TRUE (1), FR will reset 
the variable to FALSE (0), 
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string Construction 5f5 

One may modify an nhS statement or a string with the statement: 5f5a 

Sf pos -. stringlist i 

The whole statement or string in which pos resides wiu 
be replaced by the string list, 

ST pos pos *• stringlist r 

The Part of the statement or string frore the first pos to 
the secona pos will be replace^ by the string list. 
Mpos" may be a previously set text pointer or the 
sr(pos)/SE:(pos) construction. 

There are two additional ways of modifying the contents of a 

string variables 5f5b 

ST «strlngname#Cexp To expl •, stringlist j 

means, the same as 
#strlngname#Eexp to expT^ stringlist ? 

The string from the first position to the second position 
will be replaced by the string listt The 
sguare»brac)ceted range is entirely optlonali If it Is 
left off f the whole string will be replaced, 

Note that the "ST" is optional when assigning a 
stringlist to the contents of a string variable. The 
Statement then resembles any simple assignment statement, 
I»e, 

•strlngname* ^ stringlist i 

The string list (stringlist) may be any series ol string 

designators, separated by commas. The string designators may 

be any of the following: 5f5c 

the word NUl/I^ 

represents a zero length (empty) string 

string constant, e,g, "ABC or »w 

part of any string or statement, denoted either by 
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two tfxt pointers previously set In either a statement or 
a string 

PQS pos 

a string name in asterisks » revering to t^e whole string 

♦stringname* 

a string name in asterisJcs foiiowed toy an index, refering 
to a cHaracter in the string 

#stringname#cexPl 

ifhe index of the first character is one,) 

a string name in asterisks followed by two indices, 
refering to a substring of the string 

#stringnawe«cexp TO exp] 

A construction of the torff^ #str«ti TO jl refers to 
the substring starting with the ith cnaracter in 
the string up and Including the jth character, 

ExaiTiples? 

♦str*C7 ta 101 is the four character substring 
starting with the 7th character of sttt 

♦str#Ci TO str.l»3 is the string str without the 

^irs.t t»l , Characters', a Is a .declared' 
variable, ) 

+ substring 

substring capitalized 
• substring 

substring in lower case 

exp 

value of a general hiO expression taken as a character; 
i,e,, the character with the ASCII code value (see chart 
at end of docuiRent) egulvalent to the value of the 
expression 
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STRING (expl, exp2)5 

gives a string which represents the value of the 
expression expi as a signed decimal nuinber» II the 
second expression is present? a nmiRber of that base is 
produced instead of a decimal number. 

STPIHG (3*2) is the saifie as the string '•e** 

or 
STRING (14,8) is the same as the string "16« 

Exaffiplesi 5f5d 

ST pi p2 ^ ♦5trin9#; 

does the same as . . 

ST pi « SF(pl) pi, *string*, p2 SECp2)? 

assuming pi and p2 h3ive been set somewhere in the same 
stateiient. The latter r^ads '•replace the statement 
hoidihg pi with the text from the beginning of the 
stateintnt to pi, the contents of string, then the text 
froffl p2 to the end ol the statement ," 

#st*Mow TO high} ^ "string"? 

^.•doe^s ■■.the same" ■ms ■ 
#st# ^ #st#tl TO 10M»13, "stringw, «st»Chigh+l TO st»|^j7 

assuroing low and high art declared slraple variables. 

Examples 5ffe 

Let a "word" be defined as stn arbitrary number of letters and 

digits. The text pointer "t" is set before or after some 

character in the word. The two statements in this example 

delete the word which holds the text pointer "t", and if there 

is a space on the right of the word, it is also deleted. 

Otherwise, if there is space on the left of the word it is 

deleted, 5f6a 

The text pointers ptrl and ptr2 are used to delimit the left 

and right respectively of th® string to be deleted, 5f6b 

IF (FIN0 t < $l.D *ptrl > siiD (SP *ptr2 / *ptr2 ptrl < CSP •ptrl 
/ TBUE)) 3 THEU 

ST ptrl ptr2 * HUii,? 5f6c 
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The reader should voric through this example until it is clear 

that it really behaves as advertised, 5£6d 

More Than One ch«»hgt per stateffient 5f7 

The second ^ord of a text pointer> the character co^ntf stays 

the same until the text pointer is again set to some other 

position (as does the first word) # even though the statement 

has heen edited, if, lor exampXe* you have the statement 5£7a 

at)Cdefg 
/\ 

and if you h«ve set a pointer foetween the "d" $nd tne ••e'*^ it 

will always point between the fourth and fifth characters in 

the stateinent? the second word of the text pointer holds the 

nuroher 5, if you then delete the character "a", your pointer 

will be between the "e" and the "f", 5f7b 

/\' 

for tnis reason, you probably want to do a series of edits 

beginning with the last one in the statement and wOrKing 

backwards, 5f7c 

Text Pointer coj^p^risons 5f8 

This m^y be used to comp^ire two text pointers, 5f8a 

POS ptl * Pt2? 

> 

< 

>a 

ptl and pt2 are text pointers, 

NOT may precede any of the relational operators. If the 
pointers refer to different statements then all relations 
between them are FALSE except "not equal" which is written # 
or NOTa, If the pointers refer to the same statement, then 
the truth of the relation is decided on the basis of their 
location within the statement, 

A pointer closer to the front of the statement is "less 
than" a pointer closer to the end, 
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Section 7 1 Invocation of U$er Filters 5g 

introciuction 5gl 

The content Analyzer filters described in this docyinent n?ay be 
imposed through the nhS MQQ^kns subsystem, 5gla 

User*attachahie subsystewis may be written for more complex 
tasics , This type of user program and Uh$ procedures which 
may be accessed by them will be discussed in Part Four, 
with such a program, however^ the user will still maice use 
of the commands in the UhS PROGRAMS subsystem, 

This section describes nls commands which are used to compile, 
institute and execute user programs and filters, Sglb 

Compilation** 

is the process by which a set of instructions in a 
program is translated from the 140 language written in an 
nIjS source file into object code, which the computer can 
use to execute those Instructions, 

Loading*-* 

is the process which copies the compiled instructions 
into the user-programs buffer. 

Institution"* 

is the process by which a compiled and loaded Content 
Analyzer program is designated as the current Content 
Analyzer filter. 

This section additionally presents examples of the use of the 

titO programming language. They do not make use of any 

constructions not explained so far in this manual, 5glc 

Programs Subsystem 5g2 

Introduction Sg2a 

The PROGRAMS subsystfm provides several facilities for the 
processing Of user written programs and fiiterst It is 
entered by using the Hls commands 

Goto Programs OK 
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This syi3systein enables the user to compile LIO aser programs 
as well as Content Analyzer patterns, control how these are 
arranged internally for different ysesr define how programs 
are used, and to see the status of user programs, 

RROGRAMS subsystem commands 5g2b 

After entering the PROGRAMS subsystem^ you may use one of 
the following commands; 

show status of programs buffer 

This command prints out Information concerning active 
user programs and filters which have been loaded and/or 
instituted; 

Show Status (of programs buffer) OK 

When this command Is executed the system will print; 

•f the names of all the programs in the user programs 
bufferf including those generated for simple content 
Analysis patternsf starting with the first program 
loaded, 

•»• the remaining free space in the buffer • The buffer 
contains the compiled code for all the current 
compiled programs, 

»« the current Content Analyzer Program or *'None« 

•• the current user Sequence Generator program or 
"None^* 

WW the user Sort Key program or "Hone" 

Compile 

1,10 Program 

This command complies the program specified. 

Compile LIO (user program at) ADDRESS OK 

ADDRESS is the address of the first statement of the 
program. 

This command causes the program specified to be 
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coppHed and loaded Into the user program buffer In a 
single operation. The program is not instltutea. 

The name of the program Is the visible following 
the word program, AddRESS points to the PROGRAn 
statement. 

The program may be instituted by the appropriate 
commands ^ 

File 

The yser program byffer is cleared whenever the user 
resets or logs out of the system* if yoy have a long 
program which will be used periodicallyf you may wish 
to save the compiled code in a TEMEX filet It can 
then be retrieved with the Load Program command. The 
command to compile the code into a TeneX file is: 

Compile File cat) ADDRESS (using) hlQ OK (to file) 
FlliEIsAWE OK 

The fii^ENAWE must be the same as the program name. 
The program will then be compiled and stored in the 
TENEX file of the given name (with the extension REi> 
unless otherwise specified). The user may then load 

it at any time. 

Before doing thisf the programmer must replace the 
word FROCJJ'AH at the head of the program with the word 

Content Analyzer Pattern 

This command allows the user to specify a Content 
Analyzer pattern as a content Analyzer filter. 

Compile Content (analyzer filter) ADDRESS OK 

The pattern must begin with the first visible after 
the ADDRESS* or at thtt point you may type it in. It 
will read the pattern up to a semicolon, so be sure to 
Insert a semicolon where you want it to stop. 

When this command is executed, the pattern specified 
is compiled into the buffer* AND It is automatically 
Instituted as the Content Analyzer filter. 
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procedure 

This coiTJfflan<3 compiles a single procedure. 

Compile Procedure Cat) ADDRESS OK 

ADDRESS is the address of the PROCEDURE statement. 

This contmand causes the procedure specified to be 
compiled and loaded into the user program isuffer In a 
single operation. 

If a procedure of the same name has already been 
loaded (In the user programs buffer or in the nls 
system), the old procedure will be replaced, I,e, 
any calls to that procedure n&me will invoke the 
newly compiled procedure. 

Error Message during compilation 

"SYMTAX ERROR" messages include the type of error # the 
location of the line of assembly code that caused 
trouble* and a few characters of the HI4S source code. 
The last of these characters is the one which caused 
the error, in some cases this may be misleading, when 
a previous error Ce,g, a missing quote or percent 
sign) caused trouble later In the compilation, 

"ext & local" *- a symbol was used as both an 
external or global and a local variable in the 
file. If a variable is not declared in the 
program, the compiler assumes it is a system 
E)fTERi^AL, If it is later used as a LOCAli, an error 
will result, 

"field too large" •»• a field may not be defined as 
more than 36 bits, 

"sides not equal" »« in a multiple assignment 
state»eht, the sid^s must nave the same number of 
values, e,g, Ca,b,c) -» (x,y,z)f 

"not REr or POIMTER" •"» an ampersand (&) was used 
on a variable not REfed or declared as a POlflfER 
(not described in this document), 

"8 args max" »• you may not pass more than eight 
arguments ma asys call, 
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"SYSTEM ERROR" messages also incluae the type of 
error f the location of the line of assembly code that 
caused trouble I and a few characters of the nhS source 
code. 

"EOF READ" ** the compiler hit the end of the UhS 
file before it read a riNlSH stateaentt (This may 
happen if you don't have viewspecs set to all 
linesf all levelSt) 

"H^SH TABliE rilLL« •* you have used too many symhols 
in the file. Each file is limited to approxifnateiy 
2000 sytnhols, 

"BACKUP TOO Far** "^^ a symbol or a literal string 
(text within quotes) has too many characters in Itt 
They are limited to 148 characters, 

"SYMBOL TOO hom** •• as above, a symbol has too 
many characters in it, 

•'IHPUT TOO LOMG" »* as above, a literal string has 
too many characters in it, 

"S,S» FULL" •» as abovei a symbol has too many 
Characters in tt» 

"I/O ERROR" •« a number has too many digits In it, 

"LIT TABLE FULL" •• the file has too many literal 
strings and numbers, 

"PUSHDOWN OVERFLOlii" means that one of the Stacks that 
the compiler uses overflowed. Look for an LIO 
statement containing too many parentheses or 
particularly complex constructions, you may have to 
break some statements into rayitiple statemehts, 

"Boolean as operantd" •» you used an expression as a 
parameter or ih a RETURn statement. This Is NOT an 
errors but only a warnihg of unusual (though in many 
cases good) programming practice. 

If you include the LIO statement 

NOMESS f 

at the beginning of the file, at the same level as 
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global declarations Ci^e, not witiiin a procedure)^ 
this warning will not be printed. Errors will be 
printed as usual. 

When the coippilation is finished^ it will list the 
number of errors and wait for a Command Accept to 
continue, You should then search for the error in the 
NLS source code file# correct it# and recompile before 
attempting to use the program. 

Errors involving undefined variables will be reported 

when you attempt to load the program. Of course any 

code using these variables will cause execution 
errors. 

If you include the t 10 statement 

LIST ; 

anywhere in the code^ all the undefined symbols at 
that point in the compilation wm be printed. 

The Compile Procedure command will generate 
undefined variable errors legitimately if the 
procedure refers to global variables. 

If the addition of your program to the user programs 
buffer requires more than the maximum space allotted 
for user programs (either in number of pages or number 
of symbols)* you will get a "format error" upon 
loading, (if you have any other programs loaded, use 
the "Delete All" command prior to loading,) 

NDDT (described in Part Five, Section 2) will help you 
trace run^time errors to errors in the NI^S source 
code, 

l^oad Program 

A ptf •compiled prograiR existing as a rei^ file m^y be 
loaded Ihto the program buffer with the commands 

Load Program fii-e^ame ok 
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If the FILENAME is specified without specifying an 
extension name, this command win search the connected 
directory* then the <PROGPAMS> directory^ for the 
following extensionss 

nEl •* It will simply load the REL file 

GA •« It will load the program and institute it as the 
current content analyzer prograiR 

SK ••It will load the program and institute It as the 
current sort Key extractor program 

SG •• It will load the program and institute It as the 
current sequence generator program 

SUBSYS ^- it will load the program and then look: for a 
file of the same name with extension CML? if both are 
successfully loaded, they will be treated as a single 
program 

CMl -- it will load the program and then try to attach 
it as a subsystem 

PROC-HeP •• It will load the program and then try to 
replace an existing procedure of the same name as the 
TENEX code file by the first procedure In loaded 
program 

Sort Key extractor and sequence generator programs are 
more complex and are generally limited to experienced 
LlO programmers, 

FILENAME Is the name of the TENEX code file, not the name 
of the program. 

If any variables are undeflnedr they will be reported 
upon loading, Th© program should not be used until those 
variables are declared somewhere. 

Delete 

All 

This command clears all programs from the user program 
buffer. All programs are delnstituted and the buffer 
is marked as empty. 
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Delete All (programs in buffer) OK 

The user prograitis buffer stiares meraory with data pages 
for files wtiich the user i^BS open, therefore 
increasing the size of the user programs buffer 
decreases the an'ouht of space available for file data 
with a possible slowdown in response for that wser. 
The buffer size is increased autonjatically as J^eeded, 
This coR«ffland also resets the buffer size to the 
origihai 8 pages (saving system storage sptcej, 

l^ast 

This coffiBiand deletes the most recently loaded prograip 
in the buffer. The program is deinstituted if 
instituted and its space In the buffer narKed as free. 

Delete Last (progran^ in buffer) OK 

Ryn Program 

This coniiriand transfers control to the specified program. 
This type Of program is used very little, having been 
substantially replaced by user-attachable subsystems, as 

described in part Four, 

Run Prograin progname OK 
Run Prograin mumber ok 

PROCSflAME is the naJRe of a prograw wl^ich had been 
previously coipiied, Th«t iSf PROGNAHE must be in tne 
buffer when this command is executed, 

instead of PRoGNAME# the user may specify the program to 
be run by its number. This first program loaded into th® 
buffer is number onet 

institute Program 

this command enables the user to designate a program in 
the buffer as the curTent Cohtei^t Analyzert Sequence 
Generator, or Sort Key extractor program. 

Institute Program PROGHAME OK (as) type OK 

Where type is one of the following: 
Content Canalys&er) 
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Sort (Key extractor) 
Seqfuence (generator) 

If no type Is specified! Content analyzer will be 
assumed, 

Insteac3 ol PROGNAME the user may specify the program 
to be institute<3 by number. The first program loaded 
into the buffer is number one. 

If a program has already been instituted in that 
capacity! it win be deinstituted (but not removed from 
the buffer), 

Deinstitute Program 

This command deactivates the indicated program, but does 
not remove it from the buffer. It may be reinstituted at 

any time, 

Deinstitute type OK 

where type is one of the following: 
Content (analyser) 
Sort (key extractor) 
Seguence (generator) 

Assemble file 

Files written in tree^Meta can be assembled directly from 
the nis source file with the Assemble File command. This 
aspect of Nl*3 programming will not be described in this 
document t 
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Exa^i^Ples of User Programs 5g3 

Tne following are examples of user programs whiCJh selectively 

edit statements in an nhS file on the basis oi text matched 

against the pattern. For examples of LlO programming probleniSf 

you may find out how the standard ms comrnands worK by tracing 

thei through, beginning with <!ILS, SYMfAX* 2>t A table of 

contents to all the global UhS routines is available to the 

user in <MhSf SYSGO, i>, 5g3a 

Example 1 •• Content Analyzer program 5g3fo 

PROGRAM outname % removes the text and delimiters () of WLS 
statement names in parentheses from the beginning of each 
stateitient% 

DECI^ARE TEXT PQIMTER sf? 
Coutnane) PROCEDURE? 

IF ril^D '( C/)3 *sf THEiN %found and set pointer after 
na^e% 

%replace stmnt by everything after pointer% 

ST sf ^ sf SECsf )? 
%display state!nent% 

RETURN (TRUE 3? 
END 
totherwise don't display staternentt 

El.SE RETURN CFAl>SE) J 
ENP, 
FIMISH 

Example 2 *« Content Analyzer program 5g3c 

PROC^AM changed %This program checks to $ee if a statement 
was written after a certain date» if it was* the string 
"tCHANGEBI" will be put at the front of the statement, % 
( Changed) PROCEDURE j 

LOCAl* TEXT P0I1«TER pt ; 

irei^fJeWberf CCPOS is initialized to the beginning of 

each new statements 

IF FIND *pt SIMCE C25'-aAH«72 I2s00) tmU 

%the substring of zero length is replaced with 
nCHAMGED]'»% 

ST pt pt « "tCHAMGE03«j 
RETURN CEAI^SE) | 
END, 
FIMISH 
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PART FOURS Interactive 1.10 Programming 6 

Section %i Introduction 6a 

For many prograroiing applications^ it Is sufficient to accept 
statements one at a tiwe frow t^e sequence generator and assume as 
an Initial cnaracter position tlie beginning of the statewent (a 
content Analyzer prograni as described above). For more cofl^plex 
applications I you pay have to write programs which skip around 
filesf between files, and interact with the user. These are not 
called by the sequence generator but "Attached« and then used like 
standard Nl<S subsystems # holding one or more commands « All the 
capabilities described above are available to such programs, 6al 

There are two parts to every user-attachable subsystems 6a2 

1) the tlO execution routines which do the file manipulations^ 

and 6a2a 

2) the Gomiand syntax # specified in a language called cotninana 
Meta I^anguage CcMlj)* describing the user Interface of each 

command in the user attachable subsystem, 6a2b 

These two parts are two separate programs, complied separately 
into two REli flies, f he two programs are loaded m unison and 
together comprise the subsystem, 6a3 

li ike 1.1 Of source programs for the CML compiler are free form HLS 

files, eoifnraents may be used wherever a blank is permitted and the 

structure of the source file is ignored by the compiiert CML 

source pro«iraiis are compiled into REl* files with the compile File 

command in the PROGRAHS subsystem, cML is the compiler name for 

the CMl, compiler t 6a4 

The mh file name of the C^l* code should have the extension 

"cral". The REit file name of the corresponding I^IO execution 

procedurts should have the same first name as the cml code 

file, and should have the extension »'subsys," if these 

conventions are followed, the iioad progra"' command in the 

PROGRAMS subsystem will automatically load both parts of the 

user subsystem and attach it, making it available for use. The 

user's subsystem may then be Invoked by using the Goto or 

Execute commands, 6a4a 

The cut, program describes the command words, noise wordSf 
selection requests, etc, that make up an NI4S command. The CMlf 
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code interacts v*ith the user when he enters the subsystem and as 

he spectties commands. In tht process of interacting with the 

user# the CML code may Cail one or a number ol lJO execution 

procedures which "do the worK," 6a5 

CML automatically provides promptlngf questionffiarKi and 

<CTRIj*s> facilities. The CMl» syntax specification applies to 

both TnlS and dnlS (unless restricted by the programnier to one 

or the other )# and will conforffl to all user options with 

respect to prompting and to recognition and completion modes, 6a5a 

The next section win describe CMl*, and how to design the user 
Interface, section 3 explains the requirements of th© 1*110 
procedures which QUh calls. The remainder to part Four discusses 
additional 1*10 capabilities useful in the context of attachable 
subsystems, 6a6 
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Introduction 6bl 

This section describes the Coi^iaand Meta Language CCML), CML 

alXowsj the spe«:iflcation of the user interface to coRimandst 

The CML program (the grammar) may call hto procedures of a 

certain type (described in the next section), the prograros 

written in CHL are similar in structure to LlO prograws. 

Typically* a CML and an l»io prograin are used in unison as a 

user attachable subsystens, A more technical presentation of 

CHL may be found in <20438f>f 6bia 

Program Structure 6b2 

The basic CWL program structure is much llKe that of LIO 

programs, fne program begins with a «riLE" statement (as does 

an LIO program) of the formt 6b2a 

riLE name 

where name Is the name of the program code (in lowercase 
letters and numbersr beginning with a letter)? it must be a 
unigue symbols different from the FILE name of the LlO code 

In J|» iJh %M % . 

The program ends with the statement (like LlO)s 6b2b 

FINISH 

j^ithin the prof rami one may have a series (in any order) of 
declarations f rules r and subsystems, 6b2c 

AS in LlOf all variables used in the program must be 
declared somewhere in the system, other values and 
attributes must also be declared in CML, 

Rules are defined sequences of tne CML elements described 
below. Pule names can be placed anywhere In a CML command 
specification, when a rule is called within a command, It 
is almost as if the CML elements represented by that rule 
were inserted at that point in the command. This allows the 
definition of general interactions that may be of use in a 
number of commands or points in a command. 

Each program usually represents one or more subsystems* A 
subsystem may include one or more commands. Each command is 
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a rule itself. It inaY optionally include rules to be 
pertormed upon entering or leaving the subsystem, (One 
enters a subsysteir with tue Goto or Execute commands* and 
leaves with the Quit command,) A subsystem may also include 
general rules defined throughout the subsystem. 

Each of these parts of the CHL program will be described 

independently. The CML elements which make up rules will also 

be described, 6b2d 

Subsystems 6b3 

A cuh program holds declarationSf general rules which aPPiy 
throughout the program/ and subsystems (usually onlY one)t 6fo3a 

fhe subsystem begins with a statement of the form? 6b3b 

SUBSYSTEM name Keyword •♦name" 

where name is the Internal name o^^ the subsystem (primarily 
for debugging purposes) and NAME is the name which the user 
must specify (in a Goto or Execute command) to access 
commands in the subsystem. 

These two names may be the same but they must be unique, 
different from the fILe names of the CMl, and hiO files, 

A subsystem e^ds with the statements 6b3c 

END, 

if^ithin the subsystem* you may have any number of rules, 6b3d 

A rule as described below will be known throughout the 
subsystem, but not outside the subsystem, 

A rule preceded by the word "COMMAND" will be available as a 
command in the subsystem, it should begin with a command 
word element, E,g,: 

COMMAND zshow s ''SH0W"IL2I 

ent ^ ("EXAMPLEVSAMPLE") 

CONFIRM 

proc (ent) j 

A rule preceded by the word "INITIALIZATION" will be 
executed whenever the subsystem is entered (either with a 
Goto or an Execute command from another subsystem), E,g,: 
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iniiiAhiZAlwn example a 
pro<?l tent) 
proc2 cent) ; 

A rule preceaea by the word "TERMINATION" will be executed 
whenever the subsystem is left (with a Goto or Ouit command 
from this subsystem), 

h rule preceded by the word "REWTRy*V will be executed 
Whenever tne subsystem is reentered (eitner witn a Quit 
command from another subsystem, having left this one with a 
Goto, or upon completing an Execute of a command in another 
subsystem from this subsystem). 

Preceding a rule with the above modifiers does not prevent 

calling that rule from within another rule, 6b3e 

Rules 6b4 

A CMh rule is a defined series of elements, each of which 

represents one piece of the Interaction with the user or system 

action. The elements will be described below. The name of a 

rule (defined to be the given series of cnh elements) may be 

used in other rules, when the name of a rule appears ih 

another rule, the CMt code which it represents will be executed 

at that point, 6b4a 

A rule takes the form: 6b4b 

name - element 1 element2 element3 ,,, element f 

where "name" is any unique name (lowercase letters and 
numbers, beginning wltn a letter). 

Alternative elements (where the user has a choice) are 
indicated by a slash (/) in the expression. Parentheses 
should be used to group elements* particularly when 
alternative logic and nesting of alternatives is involved, 

name « (element! / elements element3) element4 i 

Note that, by use of parentheses, an alternative may 
include more than one element. 

Elements grouped in square bractcets are options* and the 
user must type the option character <CTRl«»u> to access them. 

E * q t 
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name " eXementl telefflent2 element 33 element4 ? 



E.g 



6b4c 



zin$ert « "INSERT" ent^CWORD'VwcHAR^CTER") <»at'*> 
dest«,DJSEl(ent) xins(dest)? 

A nwpber ol elements may be Included in a single rule, (If you 

exceed tbe ntasfimaffi, you will get a "stack overflow" error at 

run«»tlrae,) Elements are MOT separated by any del inj Iter 

character (except by spaces or the source file structure). The 
entire rule is terRilnated by a semicolon. 

The returh value of elements may be assigned to CMl» variables 
(singl€»word as In x*lO)# using a lef farrow C^) in the formj 

variable «, eiemerit 

The variable must have been declared, as described below, 

A variable must be initialized by such an assignment before its 
content is passed to any routine, it must be initialized in 
the rule which passes it to a routine (not lust in other rules 
called from the given rule, even though other rules raay 
subseguently set it to another value), (if you fall to do so, 
you will get the run*tlme error "reference to undefined 
Interpreter variable, w) 

Names on the left side of an assignment are assun^ed to be 
variables? other names in cml rules are assumed to be mh 
rules, 

Declarations 

Declaration^ are used to associate names with their CHL 
function, A number of types of names may be used In CML 
programs. 

Variables 

Whenever a Procedure Is called from CMLt CMl* creat^es a 
ten»word records, T^e address of the record is passed to tue 
procedure, which may put Information in any of the ten 
words. The procedure usually returns the address of its 
record. 



6b4d 



6b4e 



6b4f 

6b4g 
6b5 

6b5a 
6b5b 
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h CMh variable Is a cell which noXds the address of a CML 
record. By this jRechanism, up to ten words of inforroation 
may be handled with a single parameter by passing the 
address of the first word ol the record, a variable may be 
declared with the statement? 

DECliAPE VARIABLE nawe i 

or 
DECliARE name ? 

where "name" is any unique name (lowercase letters and 
numbersf beginning with a letter). 

You may declare any number of variables In a single 
statem.,entf !»©«! 

DECLApE VARIABLE namelr name2f,,. ; 

or 
DECLARE name I, name2,,,, ? 

Many CML variables have been declared for use anywhere in 
tbe sYsteR*' arid may be used freely in user attachable 
subsystems (without being deci^red bV the user programmer), 
some commonly used variable names are: 



ent 


namfil 


level 


pa ram 


dent 


dest 


filtre 


param2 


sent 


Source 


vs 


par am 3 


port 


from whom 


literal 


par am 4 



External Variables 6b5c 

As in LlOf external variables are variables which ai*e made 
available to any procedure anywhere in the nhs system* 
(Simple variables are only Known in the file in which they 
are declared,) c»ne or more may be declared with a statement 
of the f ormt 

DECLARE EXTERNAL nameli name2,»,, f 

Parsefunctions 6b5d 

An LlO function which processes input «nd supplies a prompt 
string is called a «parsefunction,« The name of the 
procedure must be declared ^$ a parsef unction for CML to 
request a prompt string whenever the procedure is called, 

DECLARE PaRSEFUNCTION namel, name2f,,. j 
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More detailed information about the nature of parsef unctions 
will be offered be low t 

Cowffland Words 

A consffiand word Is a wor«3 specified as part of a command 
(e,g, "insert" or "l^ord" in the insert Word coimand) I It is 
specified in accordance with each user's recognition scheme 
(often recognized after the first character) t A declaration 
may assigh a value to a command wordi to be passed to an LlO 
procedure which needs to know which command wor«3 was chosen 
by the user, 

DECLAPi: COMMAI^D ^ORD "WORDl^slOO, wijORDawaiOif , , , J 

The value must be a positive decimal integer i less thah 
5U, (This limit roay have to be changed to 255 in future 
versions of NLS,) 

More than one command word may have the sa»e value 
(unless Of course the 1,10 procedure must distinguish the 
user's choice between the two), 

clared may be included in 
hough. Only those 
value and then passed to 
Many command words have 
stem. It is considered 
already Jcnown to users 
values for those words as 
a set of declarations, 
mmand wordsi it can be 
program^ 

YOU may not use command words identical to the names of 
the LlO or Cml files# to the name of the subsystem* nor 
to any variable names. 



6b 5 e 



A command wore 


1 that has not been de 


the syntax? it 


will have 


no value t 


command words 


which are assigned a 


an LlO procedure must be 


declared. 


been declared 


for use in 


the NLS sy 


good practice 


to use command words 


when possible, 


and to use the same 


declared in NLS, section 5 offers 


including all 


the system 


defined co 


copied as the 


foundation 


for a CML 



CML Elements 6b6 

The c^L eleJ^ents described here are the building blocks of 

rulesf Which describe interactions with the user* 6b6a 

Command Word Recognition 6b6b 

The appearance of a command word element in a rule means 
that the user must specify that (or an alternative command 
word) at that point in the command specification. 
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m the CMl, description, each command word is represented 
by its full text. The alcjorithm used to match a user's 
typed input against any list of alternative command words 
is known as "recognition." Each individual's command 
word recognition mode will determine what characters the 
user must type to specify the command word* this is 
handled automatically toy the command interpreter, 

AS the user specifies a command, the command words (and 
noise words described below) are echoed in a line at the 
top of the DNiS screen, or printed in fBiLS# This is 
called the "command feedback line," 

Command word elements must be uppercase words enclosed in 
double«quotes ("")? e.g. 

"INSERT" 

Comman<3 words Optionally may be followed by one or more 
qualifiers which modify the recognition process # separated 
by spaces am enclosed in exclamation points. The 
qualifiers arei 

NOTT *• not available in THt.s 

liOTD — hot available in mis 

h2 «»•» second level (some recognition modes differentiate 
first tfom second level command words, e,g. second level 
are preceded by a space) 

number •• explicit value for command word; supercedes any 
value assigned by a declare COMmahd i^oRo 

For example; 

"Si:T"lli2i 

"PRlNT"iiOTDJ 
"EXAMPl,El¥OR0"H.2 104J 



page 107 



&ARC*ApP4»0EGw7§ 20525 34044 
ARC 34044 Pev, 5 DEC 75 NLS Programmers raulde 

Part rourj Cowand Me ta Language tCMh) 



The address of records lioXding declared coiroand word values 
may be assigned to CML variables so tt\&t the user's choice 
can be passed to subseguent routines, e,g, 

ent ^ "CHARACTER" 

or 
ent «, C "CHARACTER" / "I^ORD'*) 

then 
xprocedure cent) 

Remember that # like all other CMl, asslgnmentsi the 
variable receives the address of a record which holds the 
Inforroatlong Nhen the content of this variable (the 
address of the record) Is passed to a procedure, the 
procedure must REr its receiving variable to access the 
contents of the recordf the value. 

This value will be assigned as above even If the command 
word Is followed by ather CNL elements? e,g, 

e^t • ("CHARACTER" paraituFALSE / "WORD" <»at"> 
paraffi»LSELCf"WQRD») ) 

ent will get the value of the command word CHARACTER 
or the value of the command word mqrd. The 
appropriate actions will happen after the user chooses 
the command word. 

You may wish to pass this value without forcing the user to 
type the command word* This address may be assigned by 
preceding the command word by a pound«slgn (#), 

ent ^ # "CHARACTER" 

will assign the address of the declared command word 
value without forcing the user to type the command word 

Selection Recognition 6b6c 

selections are Input from users pointing to places In files 
or typing In strings of text. The three typeS of selection 
routines available in CMl., with their respective command 
prompts, arej 

DSeL •* destination selection 

B/A 
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SSEL ** source selection 

B/A/C1I 
LSEL *• literal selection 

B/T/ CA3 

where 8 55 bug (not available In TMXiS)# A 5 Dynamic 

Address Element cany series of nhS aaaressing elements ), 
and T « typein from iceyboard. 

Each of these predefined selection routines prompts the user 
and receives the input. 

The selection routines Riust be passed the address of a 
record holding the value of a noun command word 
(Character^ word, statefflenti plex, etc,). The command 
word enclosed in double*guotes and preceded by a 
pound»$lgn (#) is equivalent to the address of a record 
holding the declared value of that command word, e»g,8 

OSEl^CfCEARACTER") 

Or ypu may have assigned the address of the value ot a 
previously selected command word to a ci^i, variable^ then 
', pas^S;\the' content O'f .the. 'variable I e,g,j, 

ent w "CHARACTER" 
DSEL(ent) 

CML will prompt the user for the appropriate input. If 
more than one selection is necessary (e,g, to specify 
both ends of a group or string of text), they will prompt 
for both automatically. They will delimit the 
appropriate entity automatically ce^g, both ends of a 
word will be found from a single selection). 

The routine will return the address of a CML record 
holding two text pointers in the first four words* 
delimiting the beginning and end of the entity selected, 

for string entitles within statements 

words 1*2! txt ptr before first character of string 
words 3»4j txt ptr after last character of string 

for types "STATEMENT" and "BRAHCH" 
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woras l'»2: txt ptf before first character of 

statement 

words 3*«4j txt ptr after last character of 

statement 

for types "GPOOP»» and "PLEX" 

words 1*28 txt ptr before first character of first 

statement 

words 3*4jL txt ptr before first character of last 

$,tatefB,ent 

for type ^wiiidow" 

word 15 address of display area 
word 25 X and y screen coordinates 

one usually assigns the returned address of this record 
to a C^L variable* e,g,f 

dest « DSELCl^STATEMEl^f") 

Other Recognizers 6b§d 

Other prespecif led input routines are available* each 
prompting for ahd receiving a type of input from the user 5 

ViEWSPgCS •* takfef no arguwent and returns the address of 
a C^h record holding? 

word 1? updated viewspec word 1 
word 2| updated viewspec word 2 
words 3«»7i used for collecting characters f row user 

LeVADM •* takes no argument and returns the address of a 
GML record holdihg? 

word l5 level adjust count 

(up » +1, saffie » 0, down == •!, up two levels s ^2, 
etc,) 
words 2*75 used for collecting characters from user 
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comim "• Walts for user to type confirmation character 
(a Copniand Acceptf insert^ or Repeat character)? it takes 
no argument and returns the address of a cnt record 
holding the conflrroatlon code In word 1, 

These values are rarely used^ since sybsequent 
functions are handled autowatlcally by the cofiiiand 
parser. For reference^ they are: 

1 ?s Coiffiand Accept 

2 s Insert 

3 ?s Repeat 

DUMMY •« does nothing toijt always fHOE; may fee used to 
allow elements to toe sKlped, e.g^s 

( "OPTioi^*' somprocedureC) / DUnmt ) COHfipw 

allows the user to specify "Option" before the 
CONFlRMf or skip it and just type a COMFIhw, 

CWl. Constants 6b6e 

TRUE •«• holds the address of a c^l^ record whose first word 
has the value TRUE Ci«et D 

FAL3E •• holds the ad*^^®^^ of a Cm record whose first word 
has the value FAIiSE (i,e, 0) 

1.10 procedure Calls 6b6f 

1^10 procedures roay be called at any point in the rule by 
Including the name of some routine followed by Its para»eter 
list enclosed In parentheses, (The next section describes 
the special reguirements of tiO procedures called from CMli,) 

F »gt ' 

procedurename cparainlf parai2ptt«5 

Parai^eters may include CHL Variables (whose content is 
passed), th^CMi elements TRUE, FALSE or HULI^, or tne # 
construct (see "selection Recognition") representing the 
address of a command word value. 

Helpful Procedures in building CMl« logics 

isdniso *• returns TRUE if DWhS, else FAl.SE 



page lU 



&ARC*APP 4-DEC-75 20;25 34044 
ARC 34044 Rev, 5 DEC 7S NLS Programmers* Guide 

Part Four; Com?nand Meta Language (CML) 



istnisC) »• returns TRUE it tnhSt else FAtSE 

trueo •• returns TRUE 

false () «« returns FALSE 

abort () --^ abort coianjand as if user typed a CoiRmand 
Delete 

parse functions 6b6g 

Procedures whlcb are declared as PaKSefUNCTIOWs examine tbe 
information being typed by tbe user during comiRand 
specification (Characters going into the input buffer), CML 
places additional requirements on LlO procedures declared as 
parsefunctionsf as described in tbe next section. They jsay 
be called from CHL like any other LlO procedure, the 
following parsefunctions are available as part of the 
running system? tbey of course must be declared as 
parsef unctions in any program which uses them as such? 

answC) *» if the next character in the Input buffer is a 
COMFIPMf option character^ or the letter "y^f it rea<5s 
the character tout of the input buffer) and returns TRUE? 
else it reads the next character and returhs fALSe 

answer () »• reads next charaettr; liKe answ, but returns 
the address of a CML record whose first word holds either 
the value TRUE (i) or the value rALSE(O) 

lookanswC) ••• if next character is a CONFIRMf option 
character f or the letter "y"f returns true and leaves 
next character in buffer? else returns fALSe and reads 
character 

BylooKanswC)— • if next character is a CDNFiRMi option 
character # or the letter "y"f returns TRilEf else returns 
rf^hSEt leaves next character in buffer 

readcoh^ irniO ••» if next character a CONFIRM charactierf 
reads and returns TRUE? else leaves character in buffer 
and returns FALSE 

lookconf irJfif ) •• if next character is a CONFIRM # returns 
TRUE? else returns FALSe? leaves next character in buffer 

readbugO •» if next character a Coraman<3 Accept 
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character f rea<3s a^^d returns triiEj else leaves character 
in buffer and returns false 

lookbugC) ••if next character is a Cofflmand Accept # 
returns true? else returns FALSE? leaves next character 
in buffer 

notcaC) •• if next character WOT a Coiffiand Accept 
character frtads and returns TRUE? else leaves Command 
Accept character in bufter and returns FAl.SE 

readoptionO ••if next character an option character^ 
reads and returns true? else leaves character in buffer 
and returns FAl^SE 

readrepeatC) •• if next character a repeat character! 
reads and returns TRUE? else leaves character in buffer 
and returns FALSE 

looJcrptO •• if next character is a REPEAT ^ returns TRUE? 
else returns FALSEj leaves next character in buffer 

sp() •• if next character a spacff reads and returns 
TRUE? else leaves Character in buffer and returns FALSE 

looicbac*cC) ** i^ next character is a bac^^^arrow Cw) r 
returns TRUE? eise returns FALSE? leaves next character 
in buffer 

loolcnuwO •• if next character is a digit r returns TRUE? 
else returns FALSE? leaves next character in buffer 
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Parsefurjctions maY appear as alternatives to recognizers. 
However r they !«ust precede any noii*f ailing recognizers in 
the list of alternatives. EtgtJ 

( lookConfirffiC) / "APPEND" / "FILE" 3 CONFIRM 

»• this example either will accept a COMFIRH or will 
accept a specification of the command word APPEND or FILE 
followed by a COMFIRM, 

Feedback 6b6h 

Moi$e words between cofflmand words are very helpful to the 
user learning a new command. Any string of text ©ay be 
added to the command feedback line by enclosing the text in 
parentheses and within angie^brackets in a rule. E,g, 

<"Text of noise words"> 

The last noise word string on the coumand feedback line (in 
DMl«S) may be replaced with a new string by placing three 
dots before the first double*quote, e^g,? 

<,,,*'new noise words "> 

The last noise word string can be erased (in DNliS) with the 
procedure call! 

clearnameC) 

The entire coffiiand feedback line can be cleareci (in t>HhS) 
with the CHh element? 

CI.EAR 

A few characters Of the noise word will follow the command 
word in the system's response to a guestionmark ifs 

U the noise word immediately follows the command wordf 
and 

2) the command word is not being assigned to a variable 
(it way however be part of a list of alternatives being 
assigned), 

E,g, the noise words in the CHli below will show in the 
systems response to a guestionmarks 

ent * ("FILE" <«name»'> / "STATEMENT" <*'at»> ) 
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Loops 6b6i 

A looping facility permits repetition ot a different rule 
until an exit condition Is met. The rule Is evaluated and 
then the expression following the UNTIL keyword Is 
evaluated, if the expression returns TRgE# then the loop is 
exited and the next element of the rule is evaluated. If 
the expression returns FALSE, then the named rule is invoked 
once again, 

PERFORM rulenaire UNTIL ( exp ) 

where rulenan^e is the nawe of the rule to be repeatedly 
executed and exp is an expression of CML elements which 
evaluates to TRUE or FALSE, 

E,g, 

PERFORM rulename UNTIL t <«Finished?"> answc) ) 

Nested loops (loops within rules called by a PERFORM 
element) are not currently allowed, BacXspacih9 through 
executed loops re<iuires special treatment not described 

ner'e « . . 
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Sample CML Program 6b7 

The following sample program ^tiould help illustrate the use of 

the CML language for describing NLS commands, for more 

exhaustive examples* looJc at the CML specification for the 

standard NLS commands, in <NLS*syNi:AX, >, An example of a 

problem treatment can often be found by thinking of an NLS 

command which is similar, 6b7a 

FILE sampieprogram % <cml#> to <sampie,rei,> % 6fo7b 

DECLARE what, whom, where ; 
DECLARE COMHAND WORD 
"GLUE" s 1# 
"PASTE" = 2, 
"CRAYONS" s 3, 
"PENS" s 4, 
"PENCILS" = 5 ? 
SUBSYSTEM Sample KEYWORD "SAMPLE" 
Objects = 

"GLUE" 
/ "PASTE" 
/ writingthings ? 
writlngthlngs js 
"CRAYONS" 
/ "PENS" 

/ "PENCILS" »L2i J 
COMMAND ZUSe = «USE» 
what « writlngthlngs 
CLEAR 
<"to draw a pretty"> whom ^ 

C "PICTURE" <"of Aunt Mary"> 
/ "SKETCH" <"of your dog"> 
) 
CONFIRM 

% call execution routine process the USE command % 
xuseC whatr whom) ; 
COMMAND Ztake a "TAKE" 
what w^ objects 
<"out of your"> 

where ^ ("EArs^U! / "N0sE"12i / «M0UtH"13I) 
<"PLEASEii"> 
CONFIRM 

xtaKe Cwhat# where) j 
END, 
FINISH 

Given this sample CML, the user might specify the commahdi 6b7c 
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"Use Pens 
(to draw pretty) sketch (of your dog) <0K>" 

"Take Crayons (oyt of your) Wouth (PLEASElt) <0K>« 

The execution routines called from CML typically have nawes 
beginning lith the letter "x", 6b7d 
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Section 3s I#iO Execution Procedures 6c 

The CMh program interacts with the user and gathers ihformationj 

it subsequently caHs one or i«ore LlO procedures § The procedure 

CMh calls must n\eet certain requirementsi described in this 

section. Because of these requirefflents#typtcally the execution 

routine is written as an interface to a number of other LlO 

procedures perforn^lng the actual functions. This way the function 

routines can be written independent of which comiand or procedure 

calls them. This section will describe the reciuirements of 

procedures called tjom cni,^ fhe next section offers additional 

LlO capabilities in this envlronttent, ftcl 

CML can be in one of four states as it parses a comisand based on 

the syntax described in your CML prociram (known as the 

"parsemode")? 6c2 

1) parsings recognition state where input text is compared 

with graiBmatical constructs in CML program 6c2a 

2) bacKuipi the user has typed a bacKspace, or a procedure call 
has returned FALSE? CML backs up through previously specified 
elements of the c^^ code? calling each in backup roodef to 
before the last CML alternative Cnot necessarily eguivalent to 
user input element; ffiaybe through the entire commands aborting 

the command) 6c2b 

3) cleanup; ^he user has ^yi^ed a Command I^elete* or tbe 
comffiand has been completed (Including any execution procedwire 
calls) ^ CML backs up through all previously specified elements 
of the CNL codei each procedure is again called, this time in 
"cleanup" mode 6c2c 

4) parseheipj (used only with parsefunctions) before calling 
a parsefunction in *»parfing" modev the procedyre is called in 
"parseheip" mode to solicit a user prompt string» 6c2d 

5) parsegmark: (used only with parsefunctions) when the user 
types a gue^tionwarkf the procedure is called in "parsegmark" 

mode to solicit a guestionmark string, 6c2e 

When CML calls a procedure* it automatically passes two extra 

Implicit parameters before the parameters the programmier 

specifies! 6c3 

The first parat^eter Is the address of a CML record reserved lor 
use by that procedure. The record is initially eiapty (or 
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fiiled with garbage). The execution procedure may fill the ten 

words of the record by receiving the address in a REfed 

paranieter variable and then indexing into the array, 6c3a 

GMl* considers the procedure to have returned true if it 
returns the address o^ the Cuk record; otherwise the return 
is considered FAI^SE, When a procedure returns FAX,sEf CML 
Will b«cK uPf calling that and previous procedares in 
"backup" model until another branch in the corajnand syntax 
logic is found or until the entire cofBuand has been aborted. 

The second parameter is a value (not an address of a record) 

representing the parse mode, if^henever Cnh encounters a 

procedure call in the sYhtax (in any iiiode) it calls the 

procedure* passing it the value of the parseffiod«» 6c3fc) 

Typically, the execution routine should only perform its 
primary function in the parsemode "parsing**, in "backup** 
and '♦cleanup** f it may reset any globals or state information 
it may have affected while in the parsemode "parsing," The 
names of the modes Csee above) are globals to which you may 
compare the value received in the second parameter. An 
execution routine typically consists of a large CASE 
statement! e,g, 

CASE parsemode or 

5 parsing I 
BEGIN 



END? 

s backup f a cleanup: 
BEGin 

* 
mdf 

EMDCASE f 

Calls on procedures declared as parsef unctions pass a third 
implicit par«imeter# the address of a string in which to put the 
prompt. They are called in the parsemode •*parsehelp** for the 
string before being called in the parsemode "parsing** f or in 
parsemode "par$egmarlc« when the user types a questlonmarK, 6c3c 

CML passes the parameters specified in the call after the two 
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or three system supplied paraipeters, Reinember that these 
parameters will always fee the address of a record holding the 
ihforiatioh, so the receiving variable must be REfedg The 
forfnat of the record itself is determihed by the routine that 
filled it, 6c3d 

for example^ if the CHl* procedure call looiced as followsj 6c4 

xprocedure (paraisif paraffi2) 6c4a 

then the lIO execution procedure would receive parameters as 

follows! 6c5 

(xprocedure) PPoCeDUBe (result/ parsemode^ paraiieterlf 

pararoeterZ) ? 6c5a 

All parameters except the parsewode should foe REFed in the 

execution procedure, 6c5b 
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Section 4? Additional IjlO Capabilities 6cl 

introduction 6dl 

The attachable subsysteRts have access to the full capabilities 
of the Nl>S environnient. This section will describe some 
capabilities not discussed in the context of Content AnalYSser 
programs. Further capabilities will be discussed in Part Five, 6dla 

Moving Around &ilthin nhS Files 6d2 

Generallyf at least one simple variable or a text pointer will 

have to be declared to hold the statement identifier Cstid) of 

the current statement* (The first word of a text pointer is an 

stid,) Assuie the simple variable with the name ^stld" has 

been declared for the purPOge Of the following discussion, 6d2a 

In the Whs file system, two basic pointers are Kept with each 
statement! to the substatement and to the successor, 6d2b 

It there is no substatementf the substateffienf^pointer will 
point to the statement itself. 

The procedure getsub returns the stid of the 
substateiRent, To <3o something to the substateroent if 
there is one? 

IF (stid ?sr getsub(stid)) # stid fUfM soffiething,,^ 

stid is given the Value of the substateifieht^pointer , 
then tne oi<3 valye of stid is coipared to the new, if 
they ate the sa^et then there is no substructure, if 
they are differenti you have the stid of the 
substatement and can operate on it. 

If there is no successor (at the tail of a plex)# the 
successor-pointer will point to the statement UP from the 
statement (i.e, the statement to which the current statement 
is a sub) • 

The procedure getsuc returns the stid of the successor 
(or up), 

TO move to the successor} 

stid » getsuc(stid)? 
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Given these two basic procedures^ a number of other procedures 

have been written and are part of the NL5 system, AIX of the 

following procedures take an stid as their only parameter, and 

do nothing but return a value, usually a stid. If the end of 

the file is encountered, these procedures return the global 

value "endfil", 6d2c 

getup(stid) »- returns the stid of the up 

getpr<j[(stid) •» returns stid of the predecessor 

aetnxt(stld) ** returns stid of next statement or endfil 

getbcK(stid) »* returns the stid of the bacJc or ehdfil 

gethedCstid) •*" returns stid of the head of the piex 

getail(stid) — returns stid of the tail of the plex 

getend(stid) -* returns the stid of the end of the tail of 
the Plex 

getftl(stid) — returns TRUe if stid is tall of plex, else 
FALSE 

getxev(stid) •<!• returns levex of statement 

once you have the stid of a statement, you may operate on it as 

in content Analyzer procframs, E,g, 6d2d 

FIND SF(stid) $NP *ptr,.. 

Another comnson operation is to access the statement (file) in 
which the CM (or bug) was at the time of the last Cominand 
Accept Cor other coroipand terminator). This is stored in the 
system, and can be accessed with the following procedure calli 6d2e 

stid ^ IccspO ; 

Then, it you wish to set the stpsid to the origin of that 
file, you could say: 

stid, stpsid „ oriQln t %origin is a global with the 
stpsid of the origin statement in lt% 

The following procedures may also assist you in moving around 

filesj 6d2f 
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caddexp(aptrl,aptr2,aa,startptr) -- given the addresses of 
two text pointers surrounding an Uhs address expression, the 
address of a display area* and the address of a text pointer 
representing the starting position: caddexp will evaluate 
the address expression with respect to the starting 
position, and update the start pointer to the new location. 

This procedure will follow file returns, linlcSf etc,, 
opening files as necessaryt Remember to close any open 
files when you are done with them (see 6d4 below)* 

The procedure IdaC) returns the address of the display 
area whKh hel<J the bug at the time Of the last Command 
Accept; it may be used as the third parameter of caddexp, 
E,g, 

caddexp($ptrl, $ptr2, lda()# $sptr) j 

nawingrpcstidl,stid2,astring, levels) •^- given two stids 
representing a group, the address of a string holding the 
name, and a number representing levels of depth below the 
stids'? returns stld of the statement with the given 
statement name in the group specified by the stids. Only 
searches through given number of levels below stld level, 
(If the stids are the same, will search the branch,) 
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looKupCPtTrStringf type) ** given tiie address Of a text 
pointerr the address of a string, and a type, wiil do a 
variety of searches cln the process destroys string and 
changes pointer), type nay be one of the following? 

nametyp *• non«sequential search for statement of name 
given in string? returns stid and sets pointer to stid or 
else returns endfil in both places 

nxtnan^e •• like naroef also a non^seqtientlal starch, put 
starts from place in file ring to which ptr points 

seqna^e •» starting with the statement following the one 
refered to by the ptrr doe^ a seguentlal search of the 
file for the given nawej returns stid or endfil in 
pointer 

cpntnt •* does a sequential search of the file, beginning 

with the character following the pointer # for a stateaient 

with the content of the string? returns stid or endfil in 
pointer 

contls *'• sale as contnti but looks only in statement 
holding pointer 

wordtyp ••* saipe as contnt, but looks for wor^J given in 
string 

sid -"f pass an SI0 instead of the address of the stringi 
searches for statement with that 31D and returns in 
pointer and as procedure value the stid or endfil 

Calling NLS CoiPffiands 6d3 

A program may execute any of the standard NLS commands by 

calling the same procedure that the system execution routines 

call for each command. These procedures are called the "core" 

procedures. They are listed in <NL5,XPPQCS,> and in 

<NLSf SYSGDf >, Their names begin with the letter "c", generally 

followed by three initials of eacn command word, e»g, insert 

Statement could be executed by calling the procedure "cinssta", 6d3a 

Usually the required arguments can be discovered by knowing the 
command and by looking at XPROCS and/or SYSGD, For example, 
the formal parameters to the procedure "cinssta" are 
(stid,rlevcnt,tpl,tp2) , as one might guess from the command 
syntax, the procedure wants a target stid, the value of level 
adjustment (up = +1, same = 0, down = -1, etc), and the address 
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Of two text pointers syrrouncslng t^e string of text to be 

inserted, 6d3b 

Much can be learned by looking at tbe co<3e ol tbe core 
procedure. You can see wbat proceaures it in turn calls to 
cSiscover now tne command is actually performedt Bat rnost 
important ly, you can find out what tbe procedure returns, the 
RETURN statement for "cinssta»» looK like: 6d3c 

RETURHCstid)j 

from wnlcb it can ne inferred tbat tne procedure returns the 

stid of the newiy created statewentt 6d3d 

men you are not sure what the arguroents raean# a good way to 

find out is to see where the command parser picKs up the 

inforiiatlon^ You can follow through the parsing of a coraroand 

by beginning with <NiSf SYWTAX,>f the actual MLS CMh code. 6d3e 




parse a unK and open the given liief you might learn how to do 
it by following the auwp to liink coramand through. 



6d3 f 

Opening Files 6d4 

When you m^ tbe user for an address or bug^ you don*t bave to 
open the fiiey you have a handle on it wltb the stid tbe user 
gives you. There may be tlR»es, however p when you wish your 
program to open a file not specified by tbe usert There is a 
procedure which does thiss 6d4a 

open (Ithf astrlng)? 

You Should pass zero as the jfni and the address of a string 

containing tbe name of the file to astring, fhis procedure 

will returh the file number, if tbe file is not already open, 

it will open it, it will also fill out the string with the 

coiRplete file name if you do not specify the directory or 

version nuffibert 6d4b 

If tbe file does not exists open calls the procedure "err"r 
whicb generates a signal of the value "errsigt" Signals are 
discussed in Part Five, 

The usual seguence of steps to open a file is as follows? 6d4c 
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%»»sti<3^' J'as been declared as a simple variable or text 
pointer% 

St id ^ ofgstldj %orgstid is a global with ^11 zeros except 

in the stpsid field* where it has the stpsid of the origin 
statement (the saffie for every file)% 

♦str» «, «<dirnaR?e>flienaiBe,nls"? %str is of course a 
declared string varlabie% 

stld.stflle ^ open (0#$str)? 

Note that the procedure "open" requires a Tenex file name. The 
proce<3ure "inbfis" converts links to TENEX file nafftes: 6d4d 



inbfls ClinKstrr linkparsebloclc* fllenamestr) 

Pass the address of the string holding the link as the first 
parameter! Zero for the second parameter (used if llhk 
already parsed), and the address of a string to receive the 
filename as the third parameter* 

The procedure returns the host number in case the link 
includes a site name. This valye might foe compared to the 
following globalsJ 

Ihostn *** the nvimber of the local host 

utilhost -• the number of Offlce»l 

archost •• the number of the arc machine (BBW^fEHEX^B) 

For eKaiBplef you might use the procedure as follows: 

CASE inbllsC&iinkstriO#$fiiename) OF 

a Ihostnj nuhhf 

ENDCASE err (not yet) t 

At the end of your programi you should close any files that you 

have opened. Use the procedure? 6d4e 

close (filnum); 

^ • g • 

close (stidgStfile)! 
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Displaying Messages 6d5 

The foilowing procedures my be of use in displaying messages, 

in all casesf the appropriate actions will occur in TnhS as 

well as DNliS, although these descriptions are oriented to oNtS, 6d5a 

dismesCtypef astring) ^* teletype window 

where type is one oe the foi lowing s 

«•• clear teletype window (no address need be passed) 

1 ^* add text in string whose address is passed as a 
new line in the teletype window 

2 •• add text in string whose address is passed as a 
new line in the teletype window for about 3 seconds f 
then Clear window 

n »• any nuJRber >alOOO represents the number of 
billiseconds the message is to be displayed before the 
teletype window is cleared, 

in fHlSf type =5 t, 21 and >a:iooo all siinply print the 
string starting on a new line, 

ftectlCtyper astring) •• literal display window 

where type is one of the followings 

typenulllit ^•' begin empty literal display (replacing 
file window)* no string address passed 

fbaddlit •• ^^d string whose address is passed to 
current literal aisplay 

addcalit •' add «fype <CA> to continue," to current 
literal display# then wait for <CA> or <cD>f then 
restore file window 

typellt •• start literal display with strlhg, then 
wait for user inputf then restore file window 

fbendllt «« add string to current literal display^ 
then wait for us^r input, then restore file window 

typecallt *• start literal display with string# add 
"Type <ca> to continue,**, then wait for <CA> or <CD>f 
then restore file window 

The literal display replaces the file window on the 
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screen* or is simply printed in WhB^ for example^ it is 
used bf the Show File Status coitintand, 

dnCastring) *• name display 

add string whose address is passed to command feedback 
line, enclosed in quotes 

setting vp for Display Refreshing 6d6 

The cowinand parser calls the procedwre '*cmdflnish" after 

completing and cleaning up every command, if certain 

parameters are set properlyt "crsdl inish*V will automatically 

update the user's screen (primarily of concern in dj^ls). You 

may also move a different statement to the top of the window 

(i,e, jump) before updating the screen, 6d6a 

To refresh the screen after editing a file: 6d6b 

The procedure "dpset" sets up parameters for refreshing the 
screen ^tX^T a command. If "dpset" is properly ws©df the 
screen will awtomatically be refreshed after the command, 
one Should looK for the most efficient way to maKe the 
proper changes. 

The procedure "dpset" fflust be called BErORE any changes 
are made in the file, this is so that the display 
reformatter will have something with which to compare 
when looking to see what has been changed. 

The procedure call should look as follows: 

dpset ( type, stidl# stld2, stopstid ) J 

There aro a number of globals which may be passed for 
"type" J 

dsprfmt •»» rewrite the content of one or two 
statements 

stidl ** tbe stid of the statement that has been 
changed 

stid2 ** the stid of another statement that has 
been changed # or "endfll" 

stopstid ^•ignored, pass it "endfil*' 
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dspstrc •••» it tile restructuring occured beginning at 
at one or two places? doesn't rewrite content of 
statements; will add new statements in a structure 

stidl -"» the stid of the statement where a 
structural change begins 

stid2 — the stid of where another structural 
change beginsf or •♦endfil" 

stopstid *- the stid of the statement after which 
it can stop changing the screen (whether change 
began with stidl or stid2)f the procedure »»dpstp" 
may be of service here; if you cannot figure out 
where it should stop^ pass it "endfil" (go till end 
of window) 

dsprfst •♦• rewrites content of one or two statefl^entSf 
then looks for structural changes thereafter 

stldi •• tbe stid of the statement where a set of 
cbanges begins 

stld2 -- the stid of where another set of changes 
beginsf or "endfil" 

stopstid *" the stid of the statement after which 
it can stop changing the screen (whether change 
began with stidl or stid2)j the procedure "dpstp« 
may be of service here; if you cannot figure out 
where it should stop, pass it "endfil" (go till end 
of window) 

dspjpf •* Jump command in one window only# no editing 

stidl -»- the stid of the statement to be at the top 
of the screen? see below for other parameters which 
must be set 

stid2;— "endfii" ' 

stopstid »* »endfil« 
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dspyes '•• completely refresh all windows holding one 
or either of two files specified 

stidl *- the stid of a statement In the file where 
changes will be made 

stid2 -- the stid of a statement in the file where 
another set of changes will be made^ or "endfil** 

stopstid -- "endfU" 

dspno •• do no display refreshing 

stidl •*» '♦endfil" 

stld2 •«• "endfil" 

stopstid -»- Hendfil" 

•■ dspailf ^"■■refresh the "ehtlre screen.;' 

stidl •* "tnaill" 

stid2 -- «endfil» 

stopstid — "endfll" 

The procedure "dpstp", when Passed an stid^ returns the stid 
of the next statement in tne file at the same or a higher 
level. This can be used as the stopstid in "dpset" if 
structural changes are occuring such that you don't icnow a 
priori what the last statement changed will be. 

To change the position of a window (jump): 6d6c 

The Global "cspupdate" should foe set to the address of the 
display area descriptor for the window you want Changed, 

m THlSf it Is always the address contained in the global 
'♦tda". 

If yOU wish to change the view in the window which held 
the bug at the time of the last CONFIRM, you may use the 
statement: 

cspupdate ^ IdaO y 

This also worfcs for TNLS, 
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once cspopdate is set, any of the giobals described beXow 
wiiX replace the appropriate field in the display area 
descriptor upon completion ot the coroiiiand, 

The global "curroJcr" is a text pointer pointing to the 
statement at the top of a window in DJNIiS, or the Cm in TNLS, 

The first Word of "cur^Kr" should be set to the stid qI 
the statensent you want at the top of the window cin TNliS 
the statepent Which you want to hold the CH), 

The second word of »»curR5Kr"# l,e. curmkriU, should hold 
the character position for the cm. Cm j)nhS it is 
usually I,) 

The global "cspvs" is a two word array which should hold two 
viewspec words for the new view. 

The global stdvsp is a two worK array holding the HhS 
standard viewspecs (i.e, the ones in effect when Yoy 
first enter nlS), 

The current viewspec words may be gotten from the display 
area descriptor, if yoy have REFed a variable called 
'*da"f for example? you may assign the address of the 
display area Which held the cursor at the tiRte of the 
last command Accept with the statement i 

&da » IdaO 7 %return address of display area 
descriptor! 

You may then refer to fields within the display ar^a 
descriptor. 

davspec *•* holds the first viewspec word 

davspcZ »• holds the second viewspec word 

YOU way change individual fields within viewspec words. 
The following fields apply to viewspec words? 

vslev *• lowest level to be displayed 

vsriev •* if set to truE# the level of the current 
statement will be added to vslev 

vslevd •« if set to fROE and vsriev is TRUEf the 



page 131 



&ARC-APP4'«DEC»75 20 5 25 34044 
ARC 34044 Rev. 5 DEC 75 Nl^s Prograwifier$' Guiae 

Part Foyr! Additlonai lilO Capabilities 



eurrent levei will be sybtracted from ratner than 
added to vslev 

vstrnc *• nuRiber of lines of each statement to be 
displayed 

vscapf •• if TRUEf content analyzer on (viewspec i)j 
takes precedence over vscakt 

vscalcf ••II TRUEf content analyzer on until one 
statement passes (viewspec i) 

vsusqf *^ if TRUB:i user sequence generator on 
Cviewspec 0) 

vstorof *» if TRUEf branch only on (viewspec g)? takes 
precedence over vsplxf 

vsplxf ••» if TRUe# plex only on (viewspec 1) 

vsblJcl •* if TRUEf blanic lines on (viewspec y) 

vsindf •• if TRUEf indenting on (viewspec A? on by 
default) 

v5rin<3 »• if TRUEf indenting relative to first 
statewent in display (viewspec 0) 

vsnamf »* if TRUEf statement names on CviewspecCi on 
by default) 

vsstnf •* if TRUEf statefflent numbers or SIDs on 
(viewspec m) 

vsstar *• if TRUEf statement numbers/SlDs put on right 
Cviewspec G) 

vssidf ••* if fRyEr SlDs replace statement numbers 
Cviewspec I) 

vsidtf •* if TRUEf state'^ent signatures on (viewspec 
K) 

vsfrzf 't* if TRUEf frozen statements on (Viewspec 0) 

vspagf •• if TRUE* pagination on in TMi^S cviewspec Ej 
on by default) 
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vsdaft •* if TRllE# don't defer display recreation in 
DNLS (viewspec vnf on by default) 

It you wish# you roay $et the variable "cspcacod" to the 
address of a user content analyzer procedure! and/or the 
variable "cspusqcod" to the address of a user sequence 
generator procedure? they will be instituted before the 
window is updated. 

The following fields in the display area descriptor way 
be useful! 

dacacode *« holds address of currently instituted 
content Analyzer procedure 

daus<lcod •• holds address of currently instituted user 
sequence Generator procedure 

If you have a REFed variable called "da"# will not edit the 
filer and do not wish to change the viewspecst you might use 
the following sequence of commands: 

%address of last display area% 

&da ^ cspupdate\^ IdaOf 
%stid of stront to be put at top of window% 

curwicr ,» St id j. 

curPlcr Cir ^ I I 
%two current vlewspec words% 

cspvs ^ da,:dav$pecT ', 

cspvstl] ^ da,davspc2? 
%turn on Content Analyzer% 

/ csPvstvscapf ,•,, fRUf I 
%lnstitute the procedure **f ilterproc" as Content 
Analyzer! 

cspcacod «, $fiiterprocj 
%set up for display recreatlon% 

dpset Cdspjpf, curmKrf ehdfilf endfiDj 

If you have edited the filet use the type "dspyes" instead 
Of "dspjpf " in your call on "dpset" , 

Other useful procedures 6d7 

astr^ccastrlng) •« given the address of a string* sets the 

string to upper case, 6d7a 

fechnoCstldfastring)w* given an stid, appends the itateffient 

number string to the string variable whose address is passed, 6d7b 
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getstdCstid) ••given an stiaf returns value of SiD (don't 

forget to add zero to front if converting to a string) 6<37c 

fechsig(stidrastring) •» given an stidf appends the statement 
signature to the string variable whose address is passed, 6d7d 

getdatCastring) •» given the address of a string* appends date 

and tiipe to string, 6d7e 

grptst'C'Stidi?stid2> ■■♦^■■eheclcs' that two $ti<i'*s ■ ■■specify ,a'"iegal. 
aroupf returhs the^ or<3ered or else an "illegal group" signal 

is generated t 6d7f 

plxsetcstid) •» given an stid# returns the stid of the head and 

of the tail of the piex of which the passed stid is a merober? 

e.g, first ^ plxsetCstid 5 last) ? 6^79 

resetf (f ileno) •- given the file number of and open file, 
deletes all contents of the file leaving only origin stateientf 
resets date and Ident in origin statement (leaves file locked) 6d7h 

f llnaf!J(filno,a5jpring) *^ given t^e file number, appends the 

file name (in linJc forroat surrounded by angie-bra^^Kets <>) to 

string whose address is passed 6d7i 

pause(mliliseconds) •"Waits the given nurober of mini seconds , 

then returns 6d73 

settiR^er (R'iUisecondSfaproCiparaml f param2fparam3fpara!!i4) •• 

calls procedure whose address is passed* passing up to four 

parameters to that procedure^ after aiven number of 

rillisecondsj other code will toe executed in the mean time 6d7k 

Giobals of interest? 6d8 

*lnitsr* •* is the login ident of the person currently using 

the prograis, 6d8a 

inptrf -* is increinented every tiie the user types a <CfRli*o>j 

tnis can be used as a user program interrupt mecnantsif i,e, 

you can set it to at the beginning of the prograa and then 

check it at the start of each loop of your prograni to see If 

the user has typed a <CTRL*o>, i,e, wishes to abort the 

CORimand, 6d8b 

inpstp •• is incremented every time the user types a <cfRl»*s>, 6d8c 
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Section $* Creating and Usincf Attachable subsystem? 



6e 



In summary^ tbe prograpper must write two programs to build a user 
attachable subsystefRf the CMl* and the lio support procedures. 
Each of these programs is compiXed separately (by their respective 
compilers) into separate Riii files, 1*he Load program comffland (in 
the PROGRAMS sybystei?) iwiil load both at once if the extension on 
the filename holding the CMli code is "cml" and the extension on 
the Li code file is wsubsys**, once loaded^ the user may use 
commands in the subsystem as he does commands in any of the 
standard subsystems. 

You may find it convenient to begin writing a program by copying 
the following sKelton Cplex) from this UhS file 

<USERGUXDE3#l.lO*GUlDE#6e2a>, It can then be Modified to fit the 
needs of your program, Cfhe comments in the FlliE statements allow 
you to quicfcly bug the Information required by the Compile file 
command. All the cni declarations that are used in the iiIjS system 
are included only to contribute to consistent use of command words 
and values. The CMl< rules have been left blanicj they must be 
filled in or removed. All ftle# proceduret subsystemi and rule 
names are only exemplary. The last three parameters in the LIO 
procedure are only exemplary,) 

FILE cname I (CMLtSAVf) TO ccname,cml,) % 
% DECLARATIONS % 

DECLAPE PARSEFUNCTIOl^ 

% 



6el 



6e2 
6e2a 



% 



% 



ahsw f 
answeTf 
sp# 

readconf irif 
readbugi 
readoption, 
readrepeatr 
looKansw, 
lookconf irmi 
looKbug, 
looKnumi 
ciearhame, 
no tea I 
DECLARE COMHAMD 
«»BRANCH" a 1 , 
»«GRaUpw » 2 , 
«PLEX" =3 f 
"STATEMENT" a 4 
"CHARACTER" a 5 
"CONTROLCHAR" a 



reads answer consti'uct % 
for guestions * returns 
reads next charf TRUE if 
reads next char if ca % 
reads next char if BUG % 
TRUE if next Char is optchar 

Char 

char 

char 

char 

char 
% Clears .the.-name' area 
% reads next char, TRUE 

WORD 



TRUE 
TRUE 



TRUE 
TRUE 



if 

it 
if 



next 
next 
next 
next 
next 



is 

i s 
is 

X 5 



0/1 % 

space 



repeat % 

Y/CA % 

CA/REPEAT/INSERT 

BU(5 % 

a number % 

% 
if not CA Char % 



% 
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"INVISIBLE" 3 7 , 
"LINK" s 8 , 
"DIRECTORY" = 9 , 
"PASSWORD" 5 10 , 
"NU^5BER" = 11 , 
"TEXT" = 12 , 
"VISIBLE" s 13 f 
"WORD" = 14 , 
"FILE" a 15 # 
"NEWFILELINK" s 16 , 
"OLDFILELINK" = 17 , 
"NAME" = 18 , 
"IDENT" » 19 , 
"IDENTLIST" s 20 , 
"EDGE" s 21 , 
"MARKER" = 22 , 
"NL5" = 23 , 
"ITEM" = 24 , 
"XTEMNOVS" = 25 , 
"SUCCESSOR" s 26 , 
"PREDECESSOR" s 27 , 
"UP" = 28 , 
"DOWN" s 29 , 
"HEAD" s 30 , 
"TAIL" = 31 , 
"END" = 32 , 
"BACK" a 33 , 
"NEXT" = 34 , 
"ORIGIN" s 35 , 
"FILERETIJRN" s 36 f 
"RETURN" 3 37 r 
"FILENAME" * 38 , 
"FIRSTNAME" s 39 , 
"NEXTNAME" s 40 , 
"EXTNAME" a 41 , 
"FIRSTCONTENT" a 42 , 
"NEXTCONTENT" s 43 f 
"FIRSTWORD" s 44 # 
"NEXTWORD" a 45 , 
"DETACHED" = 46 , 
"TTY" a 47 , 
"AUTO" a 48 , 
"CONTINUE" = 49 , 
"ON" a 50 , 
"RECOVER" a 51 , 
"SLINKER" a 52 t 
"UPDATE" a S3 , 
"CLEAR" a 54 , 



page 136 



&ARC-APP 4-DEC»75 20l25 34044 
NLS Programmers' Guide ARC 34044 Rev, 5 DEC 75 

Part Four: Creating anol Using Attachable Subsystems 



64 



"IDENTS" = 55 9 
"FILES" = 56 , 
"DELETE" s 57 , 
"DEFERRED" s 58 , 
"IMMEDIATE" s 59 i 
"NOT" a 60 , 
"PREVENT" r 61 , 
"RESET" = 62 , 
"ARCHIVE" = 63 
"SEQUENTIAL" a 
"TWO" s 65 # 
"JUSTIFIED" s 66 , 
"ASSEMBLER" s 67 # 
"BOTH" s 68 t 
"UNDELETE" s 69 , 
"FOR" s 70 , 
"STATUS" = 71 , 
"TAPE" = 72 , 
"ACCOUNT" =: 73 , 
"NO" s 74 i 
"VERSIONS" s 75 , 
"EXTENSION" = 76 , 
"DATE" = 77 , 
"CREATION" = 78 , 
"LAST" s 79 , 
"FIRST" a 80 f 
"READ" = 81 # 
"WRITE" s 82 r 
"DUMP" = 83 , 
"EVERYTHING" = 84 , 
"LENGTH" a 85 r 
"MISCELLANEOUS" s 86 
"ACCESSES" = 87 , 
"PROTECT" = 88 , 
"SIZE" K 89 , 
"TIME" s 90 
"VERBOSE" a 
"SORT" a 92 , 
"BYTESIZE" a 93 , 
"ARCHIVED" a 94 , 
"ALL" a 95 , 
"MODIFICATIONS" a 96 r 
"UPPER" a 97 , 
"LOWER" a 98 , 
"MODE" a 99 , 
"SENDMAXL" a 100 , 
"BUSY" a 101 , 
"QUICKPRINT" a 102 , 



91 
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"PPlNtER" a 104 , 
"COM" 3 105 , 
"TERMINAL" s i06 , 
"REMOTE" s 107 , 
"REST" s 108 , 
"CASE" « 109 , 
"CONTENT" a 110 f 
"tEMPORARY" a HI. , 
"VIEWSPECS" » 112 f 
"EXTERI^AL" * 113 , 
"TO" = 114 , 
"PRIVATE" =; 115 , 
"PUBLIC" a 116 , 
"TEflEX" s 117 , 
"ALLOl^" = 118 f 
"EXECOTE" ?? 119 f 
"APPEI^D" s 120 , 
"LIST" a 121 , 
"SET" a 122 f 
"SELF" a 123 # 
"rORBiD" s 124 I 
"DISK" a 125 , 
"DEFAULT" a 126 , 
"OLD" 3? 127 , 
«MEW" * 128 f 
"COMPACT" 9 129 , 
"RENAME" a 130 , 
"ADD" a 131 , 
"SUBTRACT" « 132 f 
"MULTIPLY" a 133 , 
"DIVIDE" a 134 , 
"RiaHT" a 135 , 
"LEFT" s 136 # 
"ACTION" a 137 , 
"AUTHORS" a 138 , 
"COMMENT" a 139 , 
"EXPEDITE" 5! 140 f 
"HARDCOPY" 5: 141 , 
"INFORMATION" a 142 r 
"INSERT" « 143 , 
"KEYWORDS" a I44 , 
"OBSOLETES" s? 145 r 
"RFC" a 146 , 
"SOBCOLLECTIOHS" * 147 
"TITLE" « 148 f 
"UNRECORDED" » 149 i 
"LIO" a 150 , 
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"PROCEDURE" a 151 , 
"SEQOENERATOP" a 152 , 
"BurFER" s 153 , 
"NDDT" = 154 , 
"PAPSERULE" = 155 , 
"CA" = 156 , 
"CD" = 157 f 
"RPT" = 158 , 
"BC» = 159 f 
"BW" = 160 
"BS" a 161 , 
"LITESC" = 162 , 
"IGNORE" = 163 , 
"SC" = 164 , 
»SW" = 165 , 
"TAB" = 166 , 
"IVLAC" = 167 , 
"TI" = 168 , 
"NVT" s 169 # 
"EXECUPORT" a 170 , 
"MENU" = 171 , 
"DNLS" = 172 , 
"TNliS" s: 17 3 , 
"COMMAND" = 174 , 
"RULE" s 175 , 
"SUBSYSTEM" a 176 , 
"DISPLAY" a 177 , 
"EROZEN" = 178 , 
"HLPCOM" = 179 , 
"PROGRAM" s 180 , 
"TERSE" X 181 , 
"INDENTING" » 182 r 
"UNIVERSAL" = 183 , 
"ENTRY" s 184 , 
"INCLUDE" s 185 , 
"BOTTO!^" = 186 , 
"PAGE" a 187 , 
"OFF" s 188 , 
"FULL" s 189 , 
"PARTIAL" = 190 , 
"ANTICIPATORY" s 191 , 
"DEMAND" 5 192 , 
"FIXED" a 193 , 
"CONTROL" a 194 , 
"CURRENTCONTEXT" a 195 
"FEEDBACK" a 196 r 
"HERALD" a 197 , 
"PRINTOPTIONS" a 198 , 
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"PROMPT" s 199 , 

"RECOGNITION" a 200 , 

"STARTUP" a 201 , 

"LEVElbADJUSf" s 202 i 

"REVERSE" 5 203 , 

"TEST'» 3s 204 f 

"TASKER" 3 205 , .. 

"LIflEPROCESSOR" as 206 , 

"CEHTER" s 207 # 

"CNTLQ" 35 208 I 
% CONMON RUIZES % 

% ENTITY DEFINITIONS % 

editentity » textent / structurej 
% TEXT ENTITY DEFINITIONS % 

textent a textl / "TEXT" / "LINK"? 

textl « "CHARACTER" / "liiORD" / "VISIBLE" / "INVISIBLE" 

/ "N0HBER"? 
% STRUCTURE ENTITY DEriMITIONs % 

Structure ss "STATEMENT" / notstateinent? 

notst^tement « "GROUP" / "BRANCH" / "PLEX" ? 
SUBSYSTEM nanse KEYTORD "NAME" 
INITIALIZATION fnainel s 

, , J 
COMMAND |nalBe2 a "COMMANDWORO" 

? 

TERMINATION tnamel * 

? 

END, 
FINISH 
FILE iname % Cl»lO,3AV,) TO Clnanie.subsySf ) % 6e2b 

% giobais % 

(xname) PROCEDURE % execution procedure % 
%For«'al Paraif?eters% 

(results %result record! 
parseitiodef %parslngf backup #cleanup% 
vparaml,' ■ ■ %your first • par a»eter^,,,% • 
paramSi %of course you may have,,, % 
paraml)! %0 to 7 ol your own parameter s% 
%Locals% 

REF resultf paramlf parain2# para«3; 
cASE parseinode oF 
-9 parsing: 
BEGIN 
ENDj 
a bacKuPf a Cleanup? 
BEGIN 
EMD| 
ENDCASE? 
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RETURfJC&resuxt)j 



riNISH 
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PART fIVEf Advanced Prograin»ing Topic^ 7 

section I J Error Handling •• SIGNAL^ 7a 

introduction 7al 

When an NLS system procedure fails to perform properXyi It way 
generate an error signal. Every signal has a value* When a 
signal Is generated, control is passed bac*c to the last signal 
trap in effect. If no explicit program control statement (e,g, 
RETURN, GOTO) is given in that signal trap, a new signal will 
be generated, if the error is not dealt with# the signal will 
eventually bubble all the way back to the execution routine. 
The execution routine should always trap a signal, 7ala 

You R^ay trap signals and regain control by setting up the 

response in advance, 7alb 

Trapping Signals 7a2 

TO trap error signals of any error values 7a2a 

ON SIGNAL Ei^SE Statement ? 

E,g, 7a2b 

ON SIGNAL ELSE 
BEGIN 

dismes(2,$string)! 
RETURN; 
END? 

It is a good idea to set up a signal response before calling 

any NLS system procedures, 7a2c 

Once the signal response is setr it remains in effect through 

the end of the procedure or until it is changed^ and will be 

executed whenever a signal is received by that procedure* Any 

subseguent ON Signal statements will at that point change the 

signal response Cl,e, only one signal response can be in effect 

at any point during procedure execution), 7a2d 

Only signals generated by procedures below Ce,g, called by) 

your procedure will be trapped by your procedure's signal trap. 

It will not trap signals generated in the same procedure, 7a2e 
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The signal response may he any Cteloclc of) h%0 statement(s) , it 

Will be executed# then 7a2* 

^ if yoy have an explicit program control statement CRETURn# 
GOTO* EXIT LOOP)f control will be passed accordingly and the 
signal will stop there, or 

- if the signal trap includes no explicit program control 
statewentf another signal of the same value will be 
generated, and control will pass upward through the stack of 
procedures called until it encounters another signal trap, 

A RETURN will return control to the procedure which called the 

one which intercepted the signal (not the one which generated 

it), 7a2g 

Thusf if you wish to resume control in the current procedure^ 
the signal trap wjii n^ve to end witn a GOTO statement pointing 
to an appropriately labeled statement. This is one of the few 
places where a GOTO is really necessary, 7a2h 

If the signal trap applies to a loop, an exit LOOP or REPEAT 

LOOP is a valid signal Program control statement. 7a2i 

Trapping signals in Execution Routines 7a3 

If a signal bubbles up through the execution routine to the 
command parser (in a command in an attachable subsystem), the 
results may be unpredictable. Execution routines should always 
Include signal traps, 7a3a 

A RETURN(FAtSE) will shift CML into backup mode. It will back 
UP to before the last set of CML alternatives (not necessarily 
equivalent to the last user input elementjr and then shift back 
into parsing mode, (This may imply backing all t^e way tnrough 
the command, i,e, aborting the command,) 7a3b 

The procedure «abortsubsystem« may be useful in this context. 

It will shift the command parser into backup mode and abort the 

current command. Then it will execute a Quit (from the current 

subsystem) and return the user to the previously used 

subsystem. It should be passed the address of an error string 

to be displayed, E,g, 7a3c 

OM SIGNAL ELSE abortsubsystem ($"Error in xprocedure. ,,") j 

or 
ON SIGNAL ELSE abortsubsystem(sysrasg) ? 
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(see ^Specific Signals**) 

Cancelling signal traps 7a4 

After prograiri execution $ets up a signal respon«ef the 

following statement will cancel It so that t^^ereafter a signal 

will just bubble on up: 7a4a 

ON SIGNAL ELSE NlJtL I 

or just 
ON SIGNAL EI.SE t 

It may be subsequently reset by execution of another OM SigHAi, 
stateroentt 7a4b 

Specific Signals 7a5 

When a signal is generated, the ms system global variable 
"sysgni" is given a specific value (the value of the signal). 
Each value represents a certain type of error. Also the system 
global variable "syswsg" Is given the address of a string which 
holds an error iitessage, 7a5a 

The above constructions react to any signal* no matter what Its 
value itiay be. The ON SiGNAl statement can be used much like a 
CASE statement Ccomparlng cases to the global sysgnl) if you 
wis.h to trap specific signals.* 7aSfo 

on SlGNAt 

aconstantf statement? 
«constanti statement j 

#•»■■■■■ 
EiiSE .stateroent? 

■■■ E;tgi' 7a5C' 

ON simhi 

aoftlerrs %open file error% 

Bmm 

IF sysfflsg THEN disi€sC2#sysrosg) | 
BETURNf 
END? 
El»SE %any other error signal! 
BEGIN 

dismeSC2r$"Error") J 
REfURi? 
END? 
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the current signal constants can fc>e found in <NLSfBCOHSTi>t 
fhe coromon reason for using this specific signal treatJnent is 
when you call a procedure which you Know will generate a 
certain signal value under certain conditlonSt In such a caser 
you can learn the signal constant of concern from the siGNAt 
statement which generates it, 7a5d 

Generating Signals 7a6 

Xou ffigty generate a signal m a procedure i?y the statement f 7a6a 

SIGNAL (value* astring) i 

where value is the value ot the signal (perhaps a system 
global) and astring is the address of a string holding the 
error message, if the second parameter is omlttedi it will be 
assumed to foe zero and no message will foe printed. The first 
parameter is mandatory? every signal must have a value, 7a6b 

Examples: 

alGWAL (ofllerr* $»'couldn't open your file,") ; 
SIGNAI (2) ? 

Another way to generate a SIGNAL is by calling the proctdure 7a6c 

errcerrno) 

It will generate a sigiial of the value "errslg" (a system 
global) and will set up a message depending on the value you 
pass for errno, errno may be any of the following; 

1 •« "file copy fails"! 

2 '^^ "Open Scratch fails" f 

3 •• "Cannc>t load program'*; 

4 f«l/o Error"; 

5 •^•■•"'Excee'd 'Capacity'* I 

6 •* "Bad file block"! 

7 w "f^ot implemented" 

If you pass it the address of a string as the error 
numberr it wiii signal using that address for sysms^, and 
that string will be printed, 

Sy allowing err to generate all the signals^ you will find 
it easy to freeze execution upon an error condition while 
debugging using nddt, as described in the next section (fey 
setting a breakpoint at err). 
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Be carefgl not to call err and then trap its SIGWAL in that 
same procedure, Yom might say; 



on siQUhh 

ajerrsigs NULL? 
ELSE 9 9 « 
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Section 21 NDDT Debugging 7b 

Introduction 7bl 

Debugging is the process of finding the errors In a program « 

once the probiera i$ iocatec3f you may correct it In the source 

code CHLS file) and recompile, 7bla 

NLS includes a aeb«gginftooX called MDDTf for «NLS Dynamic 
Debugging Technique," MDDf aixows you to examine the state of 
your progran' during or after running it (i,e, using the command 
or filter). This section describes the capabilities of ^DDT, 7blb 

Accessing Nddt 7b2 

To make JlDDT available from ^hS, you must execute the comm«n<3 

in the PROCPAHS subsystems 7b2a 

Set Nddt Ccontrol»h) OK 

This adds the prograflf^ NDDT to your user programs buffer. 

Thereafter! «shenever you type a <CTRI<*h>, KLS wnx iftiitsediateiy 

be interrupted (be it in a waiting or running state) and you 

will enter nddt, nnt>f will respond with its cowiRahd hearaldf a 

right angle«brdcfcet (>), indicating that nddt is ready to 

accept a command, 7b2b 

mddT corofands are specified by typing the first character of 
the command word, 

Xou may continue with MLS (from the point where it was 

interrupted) witjt tne mddt Copland 5 7b2c 

continue OK 

Xou Pay continue Nts from a specific instruction address with 

the N0DT coiiands 7b2d 

Goto ADDRESS OK 
NDDT Address Expressions 7b3 

Everything stored in the machine ( Inst r^iet ions sin<^ variables) 

has Bn address f its location within the computer's meirory. An 
address is an octal Cfoase»eight) number, 7b3a 

The naine of a procedure or of a named hiO statement may be used 
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instead of a number. It represents the octal Ipeation oiE the 

named statement Or of the first instruction of the procedure, 7fo3fo 

Addresses (sy^fc^ols or numbers) may be combined^ to evaluate to 
some location. An expression concatenated with the following 
operators will be evaluated from left to right (no hierarchical 
ordering) to a single value: 7b3c 

<Sf> same as + 

«■■■■'■■ 

» 

/ 

Thus# a symbol may be followed by a space (or Plus-sign) and 
then an octal numbert The number is added to the location 
represented by the symbol, 7b3d 

Single»i«ford Variables 7b4 

Oftehf programmers wish to examine or modify the <-ontent$ of a 
single word at a given location, the NDDf show eommand prints 
the contents of the word at that address, 7b4a 

Show i,ocation Address ok 

where address is an address expression as defined above or 
one Of the followingi 

* •• preceding entity 

<l*F> ** next entity 

■Next ■=•• ^next entity . . 

<TAB>»» entity whose address is the content of current 
location 

umf maintains some address as your current locatiohf and the 

Show command sets this location to the one it examines t If you 

do not specify an address in a show command, th^ current 

location Is assumed, 7b4b 

HDDT can print the contents in three ways: as a Symbol followed 

by a number (to be added to the symbol location)* as a single 

number r or as text. The default printout mode is symbolic. 

The printout mode may optionally be changed in a Show command. 

The new printout mode remains in effect until subsequently 

Changed, 7b4c 
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Sftow {vocation ADDRESS <CtRI^»b> PRINTHODE OK 

where PRINTMODE is one of the foliowingr 
■Myroeric 
Symbolic 
Text 

A fast way to ao the same thing is provided with the value 

command I 7b4d 

Value of ADDRESS OK 

or 
value of ADDRESS <GfRL-b> PRIMTMODE OK 

Ifou may print and then replace the value in a word with the 

Show command J 7b4e 

Show Jbocation ADDRESS ^ eXP OK 

or 
Show liOcat ion ADDRESS <C1'RL«fo> PRIHTMODE^ EXP OK 

where EXP is an expression whose value will replace the old 
value of the given location, in adaition to the address 
expressions discjussed abovef you may use the form f 

vaiueii##value2 

jfhere "vaiuei'* is a standard expression which will be put 

in the le|t half o| the wordr and "va|,uei" is an 
expression which will be put in the right hal«^ 

string Variables 7b5 

The contents Of a s^J^iJ^g variable maV be examined and modified 

as well as simple variabieSf using the comunandi 7b5a 

show string ADDRESS OK 

Strings are always printed in text printout mode, 7b5b 

you lay print and then replace the string with the show 

command J 7fo5c 

Show string ADDRESS^ STR OK 

where STR is a literal string which fo^ type in. 
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Records IhS 

TO worK with 1,10 records* you must first set the mddt record 
pointer to the first word of an JblO record deflnittonf with the 
Coffiniandl 7b6a 

Record pointer set toj SYMBOL OK 

where SYMBOL is the name o^ some LIO record, Note that it 
may be necessary to use the MARK command (describea beiow) 
to wake local records known to the nddt system. 

This Is equivalent to the command: 7b6b 

Show Location RP - SYMBOL OK 

You may then examine all the fields of any record with the 

coifsisand? 7b6G 

Show Record ADDRESS OK 

or 
Show Record ADDRESS <CTRL^b> PRINTMODE OK 

YOU may exarrine and optionally change a single field within a 

record with the show Location command, substituting 

ADDRESS, FIELD for ADDRESS. 7b6d 

^ou may replace each field in a record with the command: 7fo6e 

Show Record address •, 

The name of each field is then printed and a new value may 
be typed in^ terminated by a Command Accept. Typing only a 
command Accept will advance to the next field of the record 
without modifying the last field. 

Built in nDDT symbols 7b7 

A number of symbols are b«ilt in to NDDT and may be used in 
address expressions, 6»i*hen they are used, PRINTMODE will be 
Ignored, since the printout mode is predefined for each of 
these symbols, 7b7a 

BUilt in Locations* Registers 7b7b 

Al •* register Ai 
A2 ** register A2 
A3 — register A3 
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A4 •» regisfcer ,A4 
Rl w» register Rl 
R2 •» register R2 
R3 •• register R3 
R4 •• register R4 

Built in Locations r Frame 7b7c 

men a procedure is calledf a "fraroe" is addea to the stack. 
It includes a word (holding the return location of that 
procedure in the right half) followed by all the parameters^ 
then all the locals, sowe predefined symbols allow you 
access the current or any previous frames and the 
Information in thew, 

m «-p contains address of current frafne 

MfkM *" contains address of previous frame 

RET •'» return location in current frame 

RP »• address of record definition of last field used 

S •» contains address of top of stacK (last LOgAI* word^ or 

whatever) 

BIG •• current frasne signal location 

Built in Records 7b7d 

BASE •* first Iraroe in procedure stack 
FRAME *» current frame description 

F ■*•' saipe as FRAME 

I^OCAIjS •• current frame hOChhS 

h •• sam.e as :i40CAliS 

RECP •«" description of current record 

R •* SMme M$ RECP 

PARMS f»» current frame parameters 

P *• same as ;pARWS 

TOP -• description of top frame in procedure stack 

Control Switches 7b7e 

EC -^^ Current symbol escaPe character (?) 

RMAMEs •» It FALSE suppresses printing of r«cord fleid names 

SF *» If FALSE disables these NDPT built in symbols 

Special character commands 7b8 

The special character commands are provided for commonly used 
functions. All but « are essentially subcommands of the SHOW 
command and are processed exactly as if they had been prece<^ed 
by the command word Show, 7b8a 
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3? •"' stiow current location in nuiertc typoat without 
changing the current printing mode 

^ *• Assign a value to current location 

* •• Show previous location 

hf *• Show next location 

TAB »• Show location addressed toy current location 

Traces and BreaKpoints 7b9 

If you set a "trace" at a location, the system will print that 

address every time that instruction is executed. Execution 

will not be interrupted, yoy may set a trace with the command? 7b9a 

Trace location ADDRgsS OK 

If yoU set a breaKpoint at a location, a <CTHI^»h> will 

automatically be executed just before the given instruction 

(causing you to interrupt execution and enter nddt). This 

allows you to interrupt execution of your prograro at a given 

point and examine and change the state of the system^ A 

breakpoint n^ay be set with the coroffiandj 7b9b 

Breakpoint Set address OK 

Each trace and breakpoint is assigned a nufflberr beginning with 

zero, when it is set, you way cancel a trace or breakpoint 

using tJiis number or using the address to which it is seti 7b9c 

Breakpoint Clear NUMBER OK 

or 
Breakpoint Clear ADDRESS OK 

YOU may cancel all traces and breakpoints that you have set 

with the coir-ffland: 7b9d 

Breakpoint Clear All ok 

You t*ay list a trace ©r breakpoint of a given numher an<^ the 
location to which it is set with the commandJ 7b9e 

Breakpoint Print NUMBeR OK 

Yqu icay list all traces a^d breakpoints, their numbers, and 

their locations with the cowmandi 7b9f 
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BreaKpomt Print OK 

A brtakpolnt may replace a previous trace or fe>reaJcpoint (new 
addrtssf saffie number) with the coroffiands lb9g 

Breakpoint Set ADDRESS <ctRL«ta> Replaces breakpoint NUMBER 
OK 

A breakpoint may be set so that it only interrupts if a 

comparison between location and a given constant is traef with 

the following coromandj 7b9h 

Breakpoint Set ADDRESS <CTm*h> Test ADDRESS ReIjOP CONSTAmT 
OK 

where ADDRESS is the location of the word to be compared, 
REliOP is one of thfe following? ss # < > <a >= 
COWSTAMT is an expression with a value, 

A breakpoint may be set so that It only interrupts if a 

procedure is called and returns true, with the following 

cofRmandr 7b9i 

Breakpoint Set ADDRgSS <CTRi,»b> Call PROCeDHRenAMe OK 

140 Procedures 7bio 

you !Ray call an xiO proeedyre from mddt with the coininan«3i TblOa 

Procedure Call PROC|;DUReWAMe ok 

If the pro^e<^wr« reguires parameters* Yq^ must list them in 

parenthesesi separated by cowmas, after the name of the 

procedure? 7bl0b 

Procedure Call FROCEPURgHAME (paraml,param2f,«,) OK 

one string, enclosed in qUotes# lay be included In the 
parameter list, e^g^t 

Procedure Call PKoCitDUReiNAMe ("literal"* paraRi2, ,,V) OK 

The return value(s)o^ a procedure call will be typed ©ut^ 7bioc 

NDDT allows you to replace an existing procedur*? with a new 
procedure. Whenever the old procedure is called anywhere in 
the system* the new procedure will be called instead. The new 
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procedure wlXl be passed the sarne parameters as were passed to 

the Old, This repXaceinent can be done with the commandi 7tol0d 

Procedure Replace O!u0MAME OK NEWMAme OK 

The name of the procedure which was replaced is saved so that 
it may be restored. The replaceinent may be canceiled with the 
command I 7bl0e 

Procedure eacK up to Oi,DNAHe OK 

syiBbois 7hn 

The systera maintairis a table of symbol names ^n<5 the addresses 
Which they represents When a user prpgratn is loadedf its 
syistaols are added to the symbol table, Thusi Cin addition to 
system giobals) the table is composed of blocks, one for each 
program, 7blla 

Each blocK is refered to by the (uniaue) name of the 
program, (This is wny the CML and SUBSYs parts of a user 
attachable subsystem must have different names in the FItE 
statement*) The list of blocks (programs) is called the 
«»marK stacK," i*ocals as well as glpfoals are recognls&ed by 
RDDT for only those user programs in the mark stack, 

toy may list the names of the blocks currently in the mark 

stack lifith the commahdi 7bltb 

Nark symbol tablet Print contents of stack OK 

A block may be deleted from the mark stack (the symbols remain 
in the' symbol table, but they are not recognized by i^DPT) with 
the commandt 7b lie 

Nark symbol table: cl«arhlock PROGRAMNAMEQK 

A block may be reinstated to the mark stack with the commandj 7blld 

Mark symbol tables Set at PtC3aRAHNAME OK 

A new (empty) block may be added to the marK stack with the 

command? 7blle 

Mark symbol table: set at hewSI/OCKnaME Ok 
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If there Is at least one blocK In the iari< stacki a new symbol 
representing some address pay be created with the comffland; 7bllf 

Define flew SYMBOLS AME OK ADDRESS OK 

syj^bols defined witn this co»J^and nave a global scope, and 
may be used to satisfy external references in ijlO user 
programs subsequently conipiled. 

Any symbol witbin a block listed in tbemaricstacJc may be 

redefined to represent a different address witb the command? 7bUg 

Define Old symbolmame ok address Ok 

If you wish to replace an existing routine by a new versioh of 

the samf routinef some method of distinguishing between new and 
old occurrences of the sawe syitibol is required. Any syft»bol 

preceded by a sen^icolon (?) refers to the old occurrence of the 
symbol, (The seinicolon has the effect of disabling the symbol 

table roarklng fi^echanisui for the given symbol, causing it to be 
identified in the "old*' section of the syrobol table,) 7bilh 

For exaroplef suppose an existing routine named TEST is to be 
replaced by a new version of tne same routine whi^h Vou t^ave 
just GOffipiled (hence is in the mark stack). The nddT 
Procedure Replace command can be used as follows? 

Procedure Replace iTgsT ok Test ok 

Scanning for Content 7b 1 2 

YOU may search a set of words for a specific content with the 
command? 7b 12a 

Find content t CONTeuT OK masked bys oK lower address I 
startaddress OK uPPer address « EUDADDrESS OK QK 

The content Of every word in the specified range will be 

compared to COMIEWT, CONTENT may be of the form of an address 

or a PDPIO machine instruction. The address and content of 

each word which matches will be printed, (note that the 

"masked by" field was ignored,) 7bl2b 

If you wish only to compare certain bits in each word to 
corresponding bits in content, you may specify a mask, A mask 
is a number (Of the address form), only those bit positions in 

which the mask has a one will be compared, (If the mask is not 
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speci£ie<if ail ones will be assumed and the entire word will be 
compared,) 7bl2c 

FirJd content 5 CONTEUT OK masked byi MASK OK iower address! 
STAjRTADDFESS OK upper address J EUD^DDBESS OK OK 

MASK may also be of eittier the adpress torn or the PDPIO 
instruction fortR, 

7l>i2d 
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section 3} Writing CML parsefunctions 7c 

Parsefunctions 7cl 

Functions which are declared with the paRSEFUNCTION attribute 
in CML are assumed to be l,10 procedures which are designed to 
be parsing functions. They are used to exan>ine the user's 
input. They are called in "parsehelp" mode before being called 
in "parsing" mode. When so called, they are passed the address 
of a string as a third implicit argument. The parsefunction 
routine should fill that string with the appropriate prompt 
characters which tell what the parsing function is looking for. Tela 

When the user is faced with alternatives which Include a 
parsefunction, the parsefunction will be called in parsemode 
"parsegmark" for the string to include in the questionmarK 
display. This string must be no greater than 24 characters, 7clb 

Sample Interpreter Parsefunction Routine 7c2 

Assume that in some command we want the typein of a number to 
appear as an alternative to some set of keywords. We can 
accomplish this by defining a parsefunction (call it looknum) 
which looks at the next Input character and succeeds if the 
next character is a digit and fails otherwise. If we write 
this function as the first alternative in some command, then 
control will pass from the Interpreter to the parsefunction 
before it passes to the keyword interpreter, 7c2ei 

Suppose our command looks like: IcZ^ 

COMMAND sample s "INSERT" 

( looknumC) <"number"> ent ^ #«NUMBER« 

/ ent ^ («TEXT"/«iiIMK«) ) 

% entity now contains an entity type C NUMBER, TEXT, or 

LINK ), ^e now use the LSEL function to get a selection 

of this type % 

source ^ LSEL(ent) 
CONFIPM 
xinsert Cent, source) j 
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The parsef unction looknyffi whleh is called by tne interpreter 
both When proipting the user and also daring the actual parse 
of the coffiffiand, 

Clooknum) PRocedoHe % look$ at the next input character ^ it 
it is a digitf then return TRUe# else return FALSE % 
% FORMAL ARGUMENTS % 

(result* % ad<?J^e5s ot the result record % 
parsefiodef % parsing mode Of the interpreter % 
string)? % address of prompting string % 
REF result f string? 
CASE parsemode OF 
a parsing: 

CAsi: lookcc) or 
but f er% 
11^ CO, 

EflDCASE 

« parsehelpj 

#string* , 
■s parsegraarki 

*string# ^ 

tmCAStt 
RETURN C&result)? 



7c2c 



%value Of next character in Input 



'911 NULL y 

RETURN! (FALSE) j 
%supply string for proitipt% 

%sapply string for guestionroark% 
"Number" $ 
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Section 4s Calculator Capabilitits 7d 

introduction 7dl 

lilO arithmetic can only worK with integers. The c^liCiJl'^'^OR 
subsystem holds a nuirbers of procedures which the user 
programmer way call to do double*precislon floating Point 
arithmetic. Floating point numbers are stored m two»word 
arrays, which the user programmer must declare, All CALCULATOR 
routines worK with these two word arrays. 7dla 

converting String to Doufole-Preclsion Floating Point 7d2 

A number in a string variable may foe converted to a floating 

point array with the procedure; 7d2a 

nfloat (astring^ awordi, aword23 

where astring is the address of a string holding the nujuber^ 
awordl is the address of the first word of the array* 

and 

aword2 is ti^e address of tl^e second word of the array. 

The number ih the string may hold a decimal point, and may be 
Preceded by a roinus»sign (•), Other characters (e»gt a dollar 
sign) fflay precede the first character of the number Ca digit* 
minus sight or decimal) j they will foe ignoredt 7d2b 

Converting Floating Point to String 7d3 

The two word array may foe converted back to a string with the 
procedure I 7d3a 

gfloutp Cavari astrihSf format) 

■^^here 

avar is the address of the (first word of the) array 
holding the floating point nuwper, and 

astring is the address of a string variable in which the 
text of the number is to be placed; 

the third parameter is ignoredi so just pass zero* 

The format of the string is dictated by the global variable 
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«afoutin," Ttie followlnf fields appXy to this gioteal Cdefault 

values are in square bracketsl? 7cl3fo 

liai *•» characters to tbe left ol the aeclmaaciOJ 

tld2 *" Characters to the right of the decimal C21 

£ld3 w* characters in exponent field t03 

round »• n«i«ber of significant digits to round to C123 round 
must be less than or eoual to fl^l f fld2 fldl + fid2 must 
be less than or equal to 12 

oflo ** go to exponent notation if left*of*decifn^l too bio 
CO} 

exsion •• if a positive exponentf use first character of 
exponent field for? COI 

«-* first digit of exponent 

1 mm »■+» 

2 ■•» a space 

exp2 *• prefix on exponentf CO] 

•» no exponent 

2 ** »D« 

3 »«p H #10*11 

dpt •* print decifflal point switch coaOfff l»bn) Cll 

dig »• print at least one digit to left of decimal (0 if 
necessary) C0a50ffri=?0n) 113 

just ** lustify number within space of three fieldsi C13 
0>« right justify by adding spaces to left 
you roust ^Iso set the 
global "calflgn to TROE 

1 •• right justify by adding "O'^s 

2 «^* right justify by adding »»«s 

3 »• left justify by adding spaces to right 

you must also set the 
global »'Gaif ig" to fAliSK 

sigh »• if a positive numberf use first character of field i 
for; CO] 

*• first digit of number 

1 •• a., space 

2 •- "+" 
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AddltionalXyi if the global "cacfig" is TRUEf the number will 

foe formatted with commas, 7d3C 

Calculations with Foatin<3 Point 7d4 

The following procedures do floating point calculations on the 

two»word arrays described above. All of the following 

procedures reguire as parameters ttie address of the (first word 

of the) arrays, 7d4a 

qcaddOfb) ** a.,«.. a 4 b 

qcsub(afb) *•• a « a « b 

gciftultCafb) *• & .^ a * b 

gcdivcaib) *• a « a / b 

gcdlvw(afb#c) ** c ^ a / b 

qcnegCa) ••' a ^ ^a 
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Section 5: fields and Records 7e 

Introduction 7el 

A set of bits within a word can t>e used witrjout affecting the 
rest of the word, (On the PDP-IO, woirds are 3&»feits long,) A 
contiguous set of bits within a word is called a field, fields 
allow more elf Icient use of storage, 7eia 

once a field is deflnedi you may apply it to any word 
(variable), it will refer to the defined set of bits in 
that word (e,g, the field "l^H" refers to the right»fflQst 18 
bits of whatever word it modifies). 

You may assign a number to or from a field by following the 

variable nawe witn a period (,), then tne name ot the field? 7eib 

var, field 

E,g, stid,stpsid » origin i 

Many fields are defined in the nis system, and «»ay be used by 

user prograR^wers, some have been roentlohed in preceding 

sections? others aay be found in the NliS source code, 7etc 

Declaring Records 7e2 

Records are always defined globally. Record definltiohs are, 
liKe global declarations/ put outside of procedures withih LIO 

f 1 1 e s f 7 e 2 a 

A record definition defines a series of fields# with the length 
(number of bits) specified for each field? 7e2b 

RECORD fieidlXlengthlr fieidZliehgthl, ,,, ? 

The fields are allocated from right to left within the word, 7e2c 

I,g, the record definition? 

RECORD rightClS], leftci7J j 

would define two fields. The field "rigt^t" refers to the 
rlght*fnost 18 bits of the word. The field "left« refers to 
the next 17 bits to the left of the field "rightt" (the 
leffraogt bit is not used in this example.) 
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A RECORD definition iray specify any number of fields. If a 

field Is defined to be too large to fit in the remaining bits 

of the current word, it is automatically defined to represent 

the first field in the next word, i,e, this and subsequent 

fields are defined from the right of the next word. This can 

extend through any number of words, 7e2d 

E»Q, the RECORD definitions 

RECORD fleldiriBJ, field2ri03, field3[18], field4C36l ; 

would define the fields as follows? 

fieldl '•* right half of word 

field? "-^ right*most tO bits in left half of word 

field3 "-- right half of next word 

field4 -* entire third word Ci,e, wordC23) 

Of course when using fields tnat refer to subsequent words, 
you must be sure that you are operating on arrays of the 
appropriate size. 

Declaring Fields 7e3 

Although you can declare single fields as described here^ the 
Practice is liir.ited, (It is useful in manipulating byte 
pointers.) user programmers should use RECORD definitions 
instead, 7e3a 

A single field may be defined with the declaration! 7e3b 

Declare fieI^D name s Caddressf size t position] ? 

where 

address is the address of the word to which the field 
refers, 

size is the nuinber of bits in the field, and 

position is the number of bits left to the right of the 
fieid 



' • 



in an assignment? the address of the word referenced is kept in 

a registert named "rp," It may be used as an index by placing 

it in parentheses. Thus a FIELD declaration referlng to the 

right half of a word is? 7e3c 
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DECLARE FIEIjD rigbtaCCrp)# I8j03 j 

The left half of the next word could be dellned; 7e3d 

DECLARE FIELD ieft»ll(rp)# 18:181 J 

The address Is held in the right half of a byte pointer, ton 
may declare a field with zero as the address^ then asslan the 
field definition plus an address to set up a byte pointers 7e3e 

DECLARE FIELD rlC3ht«rOr 18j01 | 

then 
bytepolnter * right + svariable j 

A FIELD declaration may be external as well as global? 7e3f 

DECLARE EXTERNAL FIELD naitie a Caddress, size ; position) j 
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section 65 Stacks ana Rings 7f 

Declaring Stacks and Rings 7fl 

Stacks and rings are aXlocated series of words of storage, A 

stack or ring is defined to fipld a given number of records! 

each record niay be a single or a defined number of words, you 

may "push" records onto the stack or ring and then "pop" them 

oft, .as 'described 'here,, ■ 7fla 

A stack may be declared (at the global level) with the hiO 
declaration: 7fib 

Declare stack stacknameCsizel ? 

where size is the number of one«word records in the stack. 

you nay work with records of more than one word with the stack 
declaration: 7flc 

DeCIiAki: stack stacknatneCslzefrecslzeJ ? 

where recsize is the number of words in each record. All 

records in a stack must be the same size, 

Like other declarations^ any number of stackstnay be declared 

with the same statement? tfld 

Declare stack stacknawelsize1# stacknaieCnizei recsizej # ,,,? 

Stacks' may be- .declared as ■■ ex, t;||rnai 'to 'the pro^,ira,B»i 7fie 

DECLARE EXTERf^AL STACK stackname|size,recsizf J , , , , r 

Ring declarations are identical* with the word "RING'* 

substituted for "STACK," f,g.l Tfif 

DECLARE RING ringnamecsizejf ringnamexsizeirfosizeif ,,, f 
DECLARE EXTERNAL RIMG ringname tsizef recslzel / ,,,? 

Inltiaxizlng Stacks and Rings 7f2 

Before it Is usedi a stack or ring must be initialized (iret 

cleaned up)r with the LlO statement: 7f2a 

RESET stacknawe $ 
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or 
RESET rlngnaae s 

The storage can then foe considered eroptyt The RESET statement 

can be usea whenever yoy wish to clean up tne stacic or ring, 7f2b 

Using stacks and Rings 7f 3 

You may add a record to the top of the stack or ring with the 

Uto statementi 113a 

PUSH address on stackname I 

where address is the address of the first word (perhaps the 
Single word) of the record to he added to th« stacK, 

•If you try to add more elements than the stack can hold# a 
SiGNAi4 w*iil he generated, 

'^Xf you try to add more elements than the ring can hold# 
records i«iii be replaced, starting froin the bottoin (the 
first record pushed on), 

Ifou may remove a record from the stack or ring^ and optionally 

assign it to a record variable (a simple variable or array of 

the appropriate size) with the 1,10 statements If 3b 

POP stackh^w® J 

or 
POP stackname TO address } 

where address is the address of the first word Cperhaps the 
single word) of the record to receive the record from the 

stacKii'';, 

•if you try to renove more elements than the stack currently 
holdSi a SIGWAJj Will be generated, 

• If you try to reiRove more elements than the ring currently 
holdSf records 1*111 be rereads starting f row the top, this 
should be avoided, if you did not previously fill the ring# 
this top record will hold garbage. 

You may read the first word of the record at the top of the 

stack or ring (without affecting the stack or ring) as an 

expression by enclosing the name in sguarewbracketss 7t3c 

tstacknai^el 
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The second wora (the one |>elow that one the stacic) maV be 
read as CstacKname • 11# and so on» 

E.g. 7f3d 

var «, CstacKnaffle] j 

TO use stacks and rings, one usually must Keep track of how 

many records are currently on the storage, thusi you probably 

will need to maintain a count In a simple variable in parallel 

to use of the stack or ring, 7f3e 
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Section 7 8 Using the Sequence Generator 7g 

Introduction 7gl 

The sequence Generator is used by a number of wi;^S coromanas 

which require a series of stateraents from an ms iile^ A 

Procedure may open a sequence holding a number of stateffientsi 

the Sequence Generator then passes those statements bacK, one 

at a time* every tiroe it is called, 7gla 

The sequence Generator cOnsi<iers view^pecs in choosing which 

statements to return, e,g, level truncation, if viewgpec i or 

K is on# it way call a Content Analyzer program before 

returning the statement. This allows a great deal of 

flexibility in working with a series of stateraentSt 7glb 

CO'-Routine Effect 7g2 

Once the sequence Generator decides to return a statement (or 
string) # it calls a mechanism whiCh returns control to the 
procedure that called the sequence Generator^ Thus control 
will return directly to that calling procedure, even from other 
procedures the sequence Generator has called, i,e, even if the 
return mechanisw was called from a procedure called by the 
Sequence Generator, 7g2a 

When the Sequence Generator Is called the next tiier it passes 

control to the instruction after the one which called the 

return wechaniSRi^ I,e, it continues right where it left off, 7g2b 

Thus# the sequenee Generator may call a content Analyzer 

Program which »ay return control directly to the procedure 

Which called the sequence Generator, The next time the 

sequence Generator is called, execution will begin in the 

middle of that content linaly^ierprograiR (which way later return 

through the normal RETURN stateinent to the sequence Generator), 

(Thus, the sequence Generator is behaving like a co«»routlne to 

the calling procedure.) 7g2c 
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Calling Proce<lure sequence Generator Content A^^lysser 7g2c3 

1 f * f 

2 .■ 1 1 1 "■ 

3 seqgenC&sw-) ■»■•>' i ,,, 

^ • • « .. 

3 Cft filter »-**> 1 •,, 

2 « f f 

■4'/,»., <»«»--«-»»--.,*---*-'^*»-*»*.**-**<<., '3 return, mechanism 

3 'seggent'lisw) ■■»«-^»*-*-'*-*-— ■-****-*> 4 ,, , » 

4 tt.f <**»*----w«^-.« .5 normal return" 
7 ,., <«.«-«,-••.*<< 6 return" mechanism 

Sequence l^iork j^rea 7g3 

When a Content Analyzer program is called by the sequence 
Generator* one parameter is passed, the address of an array 
called the "sequence worJc area," This array, although ignored 
by most Content Analyzer programs, holds a great deal of useful 
information, if the content Analyzer procedure receives this 
address as a parameter, and then REFs it, it may refer to the 
following fields in the sequence wor)c area (see 
<NLs#BRECORDS,seqr> for entire record declaration): 7g3a 

swstid — stid of current statement or string in sequence 

swcstid -- stid of current real STATEMENT in sequence (even 
if swstid points to a string) 

swlbstid -- stid of statement heading last branch in 
sequence 

swclvl -"» level of current statement in sequence 

swsivi — level of first statement in sequence 

swvspec -* first word of viewspecs for sequence 

swvsp2 •* second word of viewspecs for sequence 

swusqcod --» address of user Sequence Generator procedure for 
sequence 

swcacode -- address of content Analyzer procedure for 
sequence 
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swlcflg -• FALSE when sequence Is openedt TRUE once something 
has been returned by sequence 

Displaying Strings 7g4 

You may call the return inechanism from Content Analyzer 
programs while causing the sequence Generator to inject a 
string in the sequence. Under the normal circumstance* where 
the sequence is being used to put up a display or print a file 
or to do filtered editing, this allows you to inject a string 
into the output. Thus you may receive a statement* reformat it 
into a string (without editing the statement itself), and then 
display the string, 7g4a 

The following procedure injects a string in the sequence* then 
returns to the procedure that called the Sequence Generator* 7g4fo 

send (sw* astrlng) j 

where sw is the address of the sequence worJ^ area* and 
astring is the address of the string, (Remember* if you 
REFed the parameter holding the address of the sequence woric 
area* use the ampersand C&) construct when passing it to 
send,) 

Note that the co^routine effect will cause execution to picK up 
right where it left off when the Sequence Generator is called 
for the next statement. Thus* execution will begin just after 
the send. If you then RgTURl^ a value of TRUe# the statement 
itself will ALSO be displayed. Most applications of send will 
RETURN(FALSE) immediately after the call on send. 7g4c 

An example of a Content Analyzer program using send() to show 

only the first line of each statement; 7g4d 

Cfirstllne) PRoCeDURe Csw) ; %content analyzer filter to 
display only first lines% 
LOCAL TEXT POINTER ptr j 
REF SW ; 

%to hold address of sequence worJc area% 
%set pointer at end of first line% 
CASE READC OF 

= ENDchr: find *ptr ; 

= EOL; FIND ""ptr ^ptr j 

ENDCASE REPEAT CASE? 
%put first line in global strlng% 

*dspstr* « SF(ptr) Ptr ? 
%lnject string into sequence% 
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send (&$w, $dspstr) • 
%so statement won't aiso be disp3,ayed% 

RETURii (FALSE) ; 
END. 

Using Sequences 7g5 

You may open and use your own sequences in attachable 
subsysterosf This may be usefui when you wish to process a 
series <^t stateientSf perhaps only those passing certain 
requirements Ce,g, level or a Content Analyzer filter). 7g5a 

To open a sequence* you should have declared and REFed a 

variable to hold th® address of the sequence work area that 

will be reserved for your sequence^ The procedure which opens 

the sequence returns this address, 7g5b 

&SW ^ QpenseqCstidlf stid2, vspeclt vspec2r seqprocf 
caproc)? 

where 

stidl and stid2 are two stids deliniating a group in an 
NLS file that will be the source of the statements in the 
sequence, fhey roay be the sasie (for a branch). The 
sequence Generator ignores the branch only and piex only 
viewspecs, 

TO get stld2f the procedure "seqena" Jiay be usefult 
Given stidl and the two viewspec words* it checKs the 
taranchwbnly and plex^only viewspecs and returns the 
appropriate stid lor stid2, Et^t? 

&sw ^ openseq (stidlf seqendCstidlfVspecifVspec2)# 
vspeci* vspec2# seqprocr caproc)j 

vspecl and vspec2 are two words holding the viewspecs for 
the sequence. There a a number of predefined fields 
which allow you to set bits within these words, (See 
part Four f section 4,) Of particular interest to the 
sequence Generator are the level truncation (not the line 
truncation) and the content Analyzer viewspecs, 

seqproc is the address of the Sequence Generator routine 
to be used. If you pass zero* the nhS standard sequence 
Generator will be used, (User Sequence Generators are 
not described herer) 
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caproc if the address of 9 content Analyzer procedure to 
be ysed If needed by the sequence (as specified in the 
viewspecs), if none is needed, you m^y pass zero, 
passing the address of a seg«ence Is in effect 
instituting that procedure for that sequence* The 
address of the currently instituted procedure may J>® 
gotten from the display area descriptor ^ as described in 
part four, section 4, 

A call on the procedure "seqgen'' will increment the fields in 
the sequence wor^^ area to the next statement Cor string) in the 
sequence? it will return the first statement in the sequence 
the first tlnse it is called, you must pass it the address of a 
sequence worK area, e,g»i 7g5c 

seqgen (&sw) j 

seqgen retu^^ns the new SwStid field of the segyencef or 
enafil if there are no more statements In the sequence. 

you may then refer to the fields in the 3equence worK area 
for infornsatlon about that statensenti e,g,: 

swpswstid "w stid of current itetR in sequence 

sw^svclvl •• level of current itew in sequence 

When you are <3one with a sequence, you must close it by calling 
the procedure "closeseq" with the adddress of the sequence worK 
area? e^g, 1 7g5d 

closeseq(i«sw) j 



page 173 



&ARG«AP^ 4«DEC*7S 20 5 25 34044 
ARC 34044 Rev, 5 DEC 75 MLS PrograiRaers ' Guide 

part Fivei using the Sequence Generator 



A typical yse of the sequence ceJ^«rator might be as follows? 7g5e 

% set up sequence % 
% set up viewspecs % 

%get adress of display area descriptor; da is REfed 
simple variable% 
&da ^ IdaC) ? 
%get current viewspecs? vspec is IPCAIi two-word array% 
vspec ■,.^; da..,, davspec y 
vspec t 13 ^ da,davspc2 f 
%turn on Content Analyzer for this seguence% 
vsPecvscapf ^ TRUE j 
%openseq with ♦♦proc" as Content AnalVzer filter # returns 
the address of sequence work area? sw is REFed simple 
variable! 

&SW ^ openseq(soiircestid, sourcestld, vspec, vspecci1# 
da,dausqcod# $proc)? 
ON SIGNAL ELSE closeseq(&sw) j 
% loop through sequence % 
%reset control*o flag% 

inptrf ^ ? 
LOOP 

BKGIN 

IF Inptrf TRBM %user typed a controX»o% 
B'EGIM 
dismes Cl, s^user terminated process") i 

■.k.'a*T loop f'''' 

%|ncre!nent to next statement in branch you are 
processing which passed filter *'proc«; or tlse exjt% 

IF seqgen(&sw) « endfil THpN EXIT LOOP | 
%call some procedure to process current stid (could as 
well have been any k?locK of code)% 

process (sw.swst id) ? 
END.? 

% close sequence % 

OM SIGNAL ELSE j 
closeseq (&sw> ? 
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Section 8 J conditional coniplling 7h 

You may delimit blocks of code within procedures that win only be 
compiled if a constant is TRUE or FALSE, If the code is not 
conjpiiedf of course it will not be part of the code file and will 

not foe executed, 7hl 

First a constant must be defined with the Set construct Cat the 

beginning Of the file) as either zero CfALSE) or non*zero 

(TRUE), 7hia 

Then, code delimited by the string? 7hib 

%+nait5e% 

where name is the SET constant 

will only be compiled if the constant is SET to a TRUE 
value. 

Similar lyf code deliirited by the string; 7htc 

%'"naBe%' 

will only be compiled if the constant Is set to ?;ero 
CFAiiSE), 
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For example* 7h2 

if the folloiing statement appears at tfie beginning of tne 

program: 7h2a 

Set test^Oj 

then a Procedure in the program might include code delimited bY 

this construct! e,g,: 7h2b 

IjIO statement ; %normaX code* always compiiedt 

lilO statement j %normal code, always compiied% 
%'-test% 

LIO statement ? %this statement NiIjL be compiled% 

t 
LlO statement j %this statement WILL be compiled% 
%»test% 
%itest% 

LlO statement ? %this statement will MOT be compiled% 

t ■ .• • 

htO statement J %this statement will NOT be compiled% 
%+test% 
LIO statement j %normal code# always compiled^ 
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Char 


ASCII 


cnar 


ASCII 


Cf^ar 


ASCII 


Char 


ASCII 


*A 


001 


, ^ ,,.,,■„ 


V aw W' *!• tm ff0 

041 


A 


101 


a 141 


■*B''' ■■ 


002 


■,• M ■' ■ •• 


042 


B 


102 


b 


142 


*C 


003 


1 


043 


C 


103 


c 


143 


*D 


004 


$ 


044 


D 


104 


a 


144 


■^E' 


005 


% 


045 


E 


105 


e 


145 


'*!«» 


006 


& 


046 


r 


106 


t 


146 


Sell 


007 


# 


047 


G 


107 


9 


147 


BS 


010 


( 


050 


H 


UO 


h 


150 


Tab 


Oil 


) 


051 


I 


111 


i 


151 


Lr 


012 


* 


052 


a 


112 


1 


152 


VT 


013 


+ 


053 


K 


113 


k 


153 


Formfeed 014 


t 


054 


L 


114 


I 


154 


CR 


015 


m ■ 


055 


H 


115 


in 


155 


•n 


016 


• 


056 


n 


116 


n 


156 


*0 


017 


/ 


057 





117 





157 


•P 


020 





060 


p 


120 


P 


160 


•Q 


021 


I 


061 


Q 


121 


q 


161 


*R 


022 


■■ 2 ■■ 


062 


R 


122 


r 


162 


*s 


023 


3' ■• 


063 


s 


123 


■ s 


163 


*T 


024 


4 


064 


■ T •■ 


124 


t' 


164 


*U 


025 


5 


065 


U 


125 


u 


165 


*v 


026 


6 


066 


V 


126 


V 


166 


•w 


027 


7 


067 


w 


127 


w 


167 


•x 


030 


8 


070 


X 


130 


X 


170 


*1 


031 


9 


071 


Y 


131 


y 


171 


*z 


032 


; I ■ 


072 


z 


132 


z 


172 


ESC 


033 


/J 


073 


i 


133 










■■ ^ ■■•,'■ 


074 


\ 


134 










. J* 


075 


r 


135 










> 


076 


' • 


136 










• 1 


077 


'■»■ 


137 


DEL 


177 


SP 


040 


■■#■■.■ 


100 
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